The development world inside GitHub is vast and full of wonders, with lots people with different ways to conceive a piece of software. Open Source projects can present a huge challenge on how things should be done across scattered teams where common-knowledge distribution is a huge challenge on its own too.
Every developer comes from different background and can think of a solution in a number of different ways, but in order to be successful there are certain ground rules that should be put in place.
Being able to create something that followed pre-established conventions we can all agree on basically helps us:
A project complient with this standard constitutes a standard.
Basic information should be added to the header of the README.md file of your standard to identify it. First of all we have the title of the standard that should be meaningful yet short, then a short description. Lastly a category to help searchability (e.g. the targeted programming language) and the resporitory URL where the standard is located. These need to be in the following form:
---
title: Meta
description: Standard to create Open Standards
category: user-guide
repository_url: https://github.com/standards/meta
---
This section should cover why the standard should exist. Always try to include the “A project compliant with this standard…” and examples of the resultant workflow of a compliant project.
Which are the specific requirements that should be applied in order to be fully compliant. You can also point out optional requirements with a clear reference of why it is optional. At least there should be one compulsory requirement.
Any reference to documentation used to create the standard as well as any appendixes. This is optional as there may not be any resource available to add.
At least two people, with their correspondent email addresses, responsible for maintaining the standard. Also they could officiate as validators if no validator section is included. Refer to the Learn section of the Standards homepage to know more about validators job.
It can be omitted if the people added as “Maintainers” are the ones responsible of fulfilling validators tasks. Otherwise, same requirements, at least two persons with their correspondent email addresses.
The following files should exist in your repository root or inside a .github folder:
ISSUE_TEMPLATE.md fileWith the following content:
## What is the purpose of this Issue?
- Request validation (title must be "Validate owner/repo-name vX.Y.Z" being owner/repo the repository location to validate and vX.Y.Z the standard version complied)
- Propose changes
- Propose a new Standard
## Describe the purpose of this Issue a bit further
PULL_REQUEST_TEMPLATE.mdWith the following content:
## What is the purpose of this Pull Request?
## Does this Pull Request solve any existent Issue?
This project exists thanks to all the people who contribute. [Contribute].
Thank you to all our backers! 🙏 [Become a backer]
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
