Standard to create Open Standards
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:
- Measure quality in some way
- In case of software development, standards would assist a developer in understanding what a piece of software provides in order to facilitate usage
- Provide an understandable and universally accepted way to collaborate on any type of project
- Promote a healthy way to extend any project when collaboration guidelines are followed
- Bring up to speed new comers to a project being able to ramp up reading applied standards
A project complient with this standard constitutes a standard.
In a README.md file
Title, description and category
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.
Validator section (optional)
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
With 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
With the following content:
## What is the purpose of this Pull Request? ## Does this Pull Request solve any existent Issue?
- Explore section of the Standards homepage: Where you can explore all existing standards.
- Learn section of the Standards homepage: Information to understand how you can submit a new standard, propose changes to existing ones or request validation for applied standards on your projects.
This project exists thanks to all the people who contribute. [Contribute].
Thank you to all our backers!
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]