It contains all the basic requirements and guide for all OSS projects in the organization.It should be ensured that project has all the items mentioned in this guide.
- README
- Introduction(in README)
- Documentation
- Key Features of the project (in README)
- Requirements for running the project (in README)
- Quick start guide (in README)
- Coding standards
- Road Map, monthly iteration plans
- Contributing guidelines
- Code of Conduct (in README)
- Core Team members (in README)
- Created by (in README)
- License (in README)
NOTE: Some items from the above check list can be optional depending on the type of project. Add only items which are required in your project.
The items from the above checklist is explained below with example projects to help you understand and get idea of how to create it.
A brief introduction about the project. This section should emphasize the What and Why of the project.
It tells users how to use the software.Great and easy to read documentation is a sign of good project.
- use tools like docsify to create documentation.
- Documentation site must be hosted on github pages and its link should be provided in README
| READ MORE |
|---|
| https://opensource.com/article/20/7/docsify-github-pages |
| https://github.blog/2016-08-22-publish-your-project-documentation-with-github-pages/ |
This section should mention all the highlights and main components of the project.These highlights should be in bullet points, all the details of these components should be documentataion.
Example of key features from https://github.com/sindresorhus/Plash
- Show a remote or local website
- Interact with the website (“Browse Mode”)
- Automatically reload the website at a custom interval
- Show the website on a different display
- Invert website colors (fake dark mode)
- Add custom CSS to the website
- Lower the opacity
- Transparent background
- Automatically deactivate while on battery
- Audio is muted
- Single image will be aspect-filled to your screen
It should have detailed explanation about the dependencies and environmental setup to successful run the project by users.It should be beginner friendly and if there is link for the resources used should be provided, for users to read more about. For most of the times it follows the structure below,
- Dependencies
- Installing
- Running the App.
Other steps can also be added depending on the project requirements. For reference please have a look at the requirements from this project https://github.com/PatrickJS/angular-starter
Quick start guide is really helpful for users who doesnt want to understand the project completely but just want to trail and see the working of the project. It should have the steps required in brief to quickly install and start running the project.
Please have a look at this project quick start guide as an example, https://github.com/udayvunnam/xng-breadcrumb or this https://github.com/PatrickJS/angular-starter
Properly defined coding standards are really important to maintain quality of the project. It is really important that the standards are discussed in advanced and standards are documented well. Coding standard documentation should be done in another file separately, not to be added in main README.
Please have a look at this example https://github.com/Microsoft/vscode/wiki/Coding-Guidelines
All the new features should be well planned for a time period. This will help to have a vision in mind about the project path. All the features devleoped till date should also be tracked.
Please the examples for Road map and monthly iteration plan.
| Type | Link |
|---|---|
| Road Map | https://github.com/microsoft/vscode/wiki/Roadmap |
| Monthly Iterations | https://github.com/microsoft/vscode/wiki/Iteration-Plans |
This seciton should have all details for the users to start contributing. The contribution can be from any one and for lot of things (issue, documentation , code etc). contibutting details should be in another file named contributing.md . All the details should be easy enough for a beginner to start contributing.
A very good example of contributing guide line is https://github.com/ngx-builders/ngx-bulma/blob/main/CONTRIBUTING.md
