Modern Library Development Guide Series front-end (c): Note from past lives to see the document library

Foreword

We work a lot of time to do technology selection, to find that meets their needs and reliable third-party libraries; in thriving open source front-end eco-quarter current situation, as long as not too public demand, we can easily to find a bunch of related open source library that we make decisions specific to how it? My approach is to first open source library to read the documentation so that they have an emotional understanding, and then pick out two or three libraries for deeper and more comprehensive understanding. That being said, this documentation is not much like when we resume the job it? "Resume" could not have been closed, so what "offer" ah!

This article describes a library (ie, not limited to the front end of the field) to be included in the documentation, including README.md , CHANGELOG.md , LICENSE , the documentation required to be placed in the root directory of the project.

README.md

As we enter one of the open source code repository in GitHub page, in addition to project information, code directory structure, the first thing that catches the eye is README.md , and seen as important as index.html it on a website.

README.md need to meet the following requirements:

Accurate (including capitalization) namedREADME.md
In line with markdown syntax
Each chapter should have a title
In English and connections should be separated by spaces
Use markdown syntax wrap snippets, and note that the language code segment marked, such as:
```
console.log('code in javascript');
```

It must contain a

A good README.md need to include the following:

Name: must be consistent with the name of the library.
Description: The markdown syntax >beginning; try to keep it simple and word count should be less than 120 ; (if any) and npm package (also if any) description consistent with the GitHub repository.
Installation libraries: how to install the library, at the front end of the field generally refers to a package or how to install npm <script>load CDN resources.
Use library: How to use this library, you can list the simplest usage, allowing users with the fastest speed to run up the library, which can efficiently build user's trust.
Open source license agreement: Copyright This library below will detail.
API: The method includes information provided by the library, parameters, events and so on.

Optional content

In addition to the above content must contain, README.md there are a number of user-friendly content items, these items tend to be considerably content to your library, so if you can, please add to your library README.md on:

Contents: The link with the anchor jump, you can use tools to automatically generate a title based on the levels README.md, please refer to GitHub-Markdown-toc .
LOGO: LOGO A good logo will be visually identify your library, your library make it easier for users to remember and to be accepted.
Badges: Badges by shileds.io provide a picture, the picture can also attach a hyperlink on demand; badge commonly used to describe this outstanding project in the state and data from external third-party platforms, such as continuous integration status of the project (if this library equipped with unit testing in general, then it will also include the code test coverage), projects in downloads a platform (often referred to as the front end of the field npm), the project released the latest version, open source license.
Browser compatibility: If the library is running in a browser environment, the statement browser compatibility of the library can help users quickly complete technology selection.
Security risk: for a list of the library has currently been found and not addressed security vulnerabilities and risk level, if the method also bypasses Please attach, which can also help users to quickly make technology selection.

CHANGELOG.md

CHANGELOG.md record of each version of the official release of the library, and the contents contained in this release. GitHub open source library for it, CHANGELOG.md content should GitHub of releases consistent.

CHANGELOG.md specifically include the following:

version number
- New features (new features)
- Optimization (optimization)
- Bug fixes (bug fixes)
- breaking changes
- Documentation (docs)

If you feel more difficult to maintain CHANGELOG.md, then in fact there are tools to analyze generate CHANGELOG.md commit message from each of the library, but there are certain requirements of normative commit message, and subsequent articles in this series where there will be detailed introduction.

LICENSE

LICENSE is the copyright notice of the library, users can use the statement to what extent, secondary development, commercial this library, have the force of law, can generally be declared directly use existing protocols, such as the GPL / BSD / MIT / Mozilla / Apache / LGPL etc. This article does not describe how to select the appropriate protocol, refer to "how to choose an open source license? " .

LICENSE technology selection for commercial projects have this vote of negative position because some open-source protocol has contagious , if your project uses this open source library, you must also open source project, which for commercial projects almost unacceptable.

Mainstream front-end framework React, claiming LICENSE problems, caused strong resentment among the community, and many large companies have been abandoned, and ultimately forced under pressure before switching to the most liberal MIT license, this storm subsided.

multi-language

Please correct assessment of your user community developed by the library, if the library user groups included in his country's people, they are ready to ask for the appropriate language documentation. For a while the public source code repository hosted open source project, I recommend at least two sets of documentation prepared in English, which will greatly expand the user base of open source libraries, since after all, hard to do out of open source libraries, or total Star would like to gain points and Fork Well hey ~ ~

Generally, we will default to a documentation is in English, and the file name plus the use of other languages in the documentation of the IETF language code , such as Simplified Chinese is the IETF language code zh-CN, so README.md the Chinese document named README.zh-CN.md, CHANGELOG .md documents named in Chinese CHANGELOG.zh-CN.md, and only need a LICENSE English is sufficient.

Examples of project code Description

I will I recently wrote two open source libraries: JavaScript-Library-boilerplate and vue-directive-window to the project as an example code to assist introduction.

javascript-library-boilerplate

javascript-library-boilerplate is a quick build scaffolding javascript library of modern front-end eco (also known as a seed project, also known as sample code, see you understand), this library supports the GitHub repository templates feature, you can click directly on the project home page Use this template to directly apply this scaffolding code to create your own javascript library.

vue-directive-window

vue-directive-window is a modal box allows quick (Modal) enhanced support window class library operation; window-based operation includes three categories: dragging movement, drag resize the window, maximize the window; vue-directive -window Vue supports custom commands or general js class way to invoke.

vue-directive-window relative to the javascript-library-boilerplate, the closer Vue ecosystem, if you want to contribute to the Vue recently ecosystem, may wish to refer this project.

Series catalog (synchronous update)

I want to read more technical articles? I go to the GitHub blog Array-Huang / blog to, if there is help for you, please take a Star & Watch Bo Ha (〃 ^ ω ^)