background

We are usually in the project development, the general will upload the code to the code hosting platform to facilitate management and maintenance. At present, the most commonly used hosting platform is Github, and there are some well-known code hosting platforms at home and abroad, such as Gitlab, BitBucket, code cloud and code market.

But under the collaboration on development, we often encounter is the most headaches, other developers in the transition to give us a project just simply describes the function of the project currently existing, we in the subsequent iteration function when suddenly discovered how to run even the most basic project didn’t give us replacement, when in ten thousand the horse pentium, Just go to the package.json scripts and get the idea.

So the question is, when we hand over a project, how do we ensure that the project can be delivered to a gay friend quickly and completely, and then live a carefree life? The answer is that we just need to throw him a README of standard specifications.

What is required for a canonical README

Let’s take a look at what a simple README specification looks like with a screenshot:

The readME specification template above can be seen in our FEFlow readME specification

So let’s talk about what a complete README specification should look like.

1. Project Description 2. How to Run 3Copy the code

What does each of these do?

  • Project description

    We need to explain our project name, project function description, code warehouse address, and the first person in charge of the project. Whoever hands over the project to us is the first person in charge of the project.

  • How to run

    1. Development environment configuration. It is usually some runtime configuration that we need.
    2. Develop & issue commands. How do we start local development with commands and build releases.
    3. Proxy configuration. If our project needs a proxy tool for local development, such as Fiddler or whistle, we need to list the proxy configuration items. It is best to export an agent configuration file directly under the project
    4. Release. If we use some publishing platforms, it is best to paste the project’s release module and release sheet, to reduce the time cost of our release.
    5. Error alarm and monitoring. I believe that we usually deploy error alarm and monitoring log services for online projects, so that we can timely troubleshoot network problems. Here we can add some monitoring attribute ids of the project
    6. Interface API. Here we need to paste the address and description of the background interface pulled in the project, as well as the person in charge of our interface. When the background service is abnormal, we can directly contact the background students.
    7. Data reporting. We have added some data reporting in the ordinary project, for the product students to statistical business data, here we had better explain what data reporting. If there is a problem reported, the product sister came to us, we are not confused.

  • Business introduction

    For the front end, we may have more than one page for a project, so we need to give the following information:

    1. Business entry address and channel link is the entry page of our whole project, or the address of more important pages. The general entry page, we may be in more than one channel, so we need to list all the channel links

    2. The pages and descriptions list all the page information in our project, such as:

      Page directory Page description The page link Parameters to describe
      index Home page now.qq.com There is no

  • Project comments In the project, we need to tell other developers some key information, such as our page packaging and building, what problems to pay attention to, etc., although this information is not necessary, it can help other developers reduce the risk and cost of development.

The last

The above is some of the information and content we need for a canonical README. The bold content is what I think is necessary for the README. You can also extend the canonical information based on the actual development scenario of your project.

“IVWEB Technology Weekly” shock online, pay attention to the public number: IVWEB community, weekly timing push quality articles.

  • Weekly articles collection: weekly
  • Team open source project: Feflow