Here is what you need to know about this initiative to get you started. This initiative relies on the community, we couldn't do it without you pitching in to write down and apply a common way to work within your team and with other teams.

Table of content

Why standards?

What is a standard?

Where does standards live?

Create a new standard

Evolve an existent standard

Complying with a standard

Why standards?

The open-source community is huge, we all come from different places from different backgrounds, with different ways to resolve problems.

In this new era where collaboration is a big part of being able to come to the best possible solution, having standards that could help us all have common ground on how to resolve certain problems sounds like a basic requirement.

Being able to create something that followed pre-established conventions we can all agree on basically helps us:

What is a standard?

Generally, a standard is a common format accepted and used by a group of people which promotes interoperability so that when a project complies with a standard, anyone knows what to expect from it. The level of commitment with a standard provides certain assurance to others and are commonly mandatory to comply with.

On the other hand, it’s worth mentioning what a guideline is in order to compare concepts. Guidelines constitutes a piece of advice on how to act in a given situation, they are not mandatory and can’t be fully measured as they provide take it or leave it suggestions.

For this initiative, no project will be forced to comply with any standard; it’s not mandatory but recommended. This is because the whole idea behind this initiative is to provide a tool that we can all contribute freely and see value in it. Eventually it may happen that the community pushes everyone to comply with them, but that needs to happen naturally to avoid any strong feelings.

Also, a standard need to define at least certain mandatory rules to be applied aside from optional ones. Otherwise it will end up defining guidelines that can’t be really verified that they were applied as part of the complying process.

Where does standards live?

This initiative strongly relies on GitHub capabilities, such like Issues, Releases and README files. That’s because GitHub hosts the largest number of open-source projects represented by a GitHub repository of files that also relies on the same GitHub capabilities.

Specifically, a standard is represented by a repository which includes markdown files with at least a README.md file to describe the standard purpose and mandatory/optional requirements. Inside a repository, a standard uses the Issues GitHub capability to bring everyone together in discussion about the standard itself and to request the standard’s maintainers to validate certain project complies with it. Also, a standard necessarily needs to release new versions when it gets updated using GitHub Releases in order to keep track its evolution and to identify if projects complies with the latest version.

As mentioned, a repository needs to follow mandatory/optional requirements to be able to create a complete and usable standard. Which is why there is a standard called Meta to create new standards, meta meaning self-referential.

Create a new standard

Hopefully this initiative get you exited enough to try to create a new standard. Remember that community is very important to make this happen so please give it a try and whatever question that may arise please do not hesitate to contact us on Gitter Shere.

Here are the official steps to create a standard to be part of this initiative:

Ideate a new standard

First of all, you may want to explore what standards exist at the moment before going ahead and create one. This is just in case there is one already. If that's the case, you may want to revise it and propose changes to it instead of creating a new one. More information in the "Evolve an existent standard" section.

Other than that, feel free to think of any kind of standard that would make your life and others' around you easier. A standard should cover basic to advanced set of rules (some optional may exist). Those rules should be easily verifiable so that when others apply the rules on their project and ask for compliance validation, validators of the standard can verify the project actually follows those rules. That is, a standard should not cover as an example, ways to resolve certain problems, as that means validators will need to go over the entire code base to verify it.

Submit it to the meta standard

Once you have a solid idea for a standard that does not exist yet, you can go ahead and submit it to the meta standard as a Github Issue. Here is a shortcut link to do that: Submit Issue to meta standard.

Note that you will be asked for the following information:

  1. What is the purpose of this Issue?: In this case you are proposing a new standard so just delete the other options.
  2. Describe the purpose of this issue a bit further: You may now describe the standard you are proposing to create. You can also include links with information about other standards out there that are serving as inspiration. Anything related to why the standard should exist so that others can engage on discussing it till it reaches a good state where the Standards maintainers, which are the meta standard maintainers, can give you the green light for creating such a standard.

Invite people into the discussion

It's really important that the community takes a huge part of creating new standards as it's the community that is going to make them their own, evolve them and work with them. There is no use of a standard proposed, created and used by a single person. We need various points of views, different knowledge put together to construct the way we all want to work with each other.

For that reason, is vital that you invite more people into the submitted standard. Just mention them on a comment typing "@" followed by their Github handle (you can grab it by the last part of the URL of their profile), asking for their opinion. Include resources of existent standards out there to base your standard on in order to kick start the discussion.

Get your new standard approved by Standards maintainers

Once you have a very fruitful standard discussion where resources where shared and a clear roadmap of how a standard should be written so it benefits everyone, you can mention @Standards/maintainers to bring the maintainers attention and to ask for approval.

This approval request is just to get feedback about what was described in the last 3 steps. If you have an unique standard proposal with a healthy discussion and people involved, you will get approval, don't worry. This step is important to avoid creating a bunch of similar standards or standards without community involvement.

Start working on the standard definition

You are all set to work on the definition of the standard. You will need to follow the meta standard which is the standard for creating standards.

You can work on the new standard creating a new public repository in your own profile or even within an organization you manage. The important thing is that you create a public repository somewhere and follow the meta standard.

Get your standard validated for its publication

The final step comes when you worked on the standard following the meta standard and you are satisfied with the result. In this step, you will submit a new issue in the meta standard but this time requesting validation, so just delete the other options.

In the description you will need to include a link to the repository that constitutes the new standard you worked on so that Standard maintainers can check that it follows the meta standard.

If everything needs to be modified/added, maintainers will give the appropriate feedback through that submitted issue. If everything looks good, you will be asked to:

  1. create a new release for your standard to start versioning its changes;
  2. include a badge in the README file, like the one the meta standard has pointing to the correct version of the meta standard that was followed.

Once that's done, the maintainers will add the standard to the list of curated standard to start showing it in the explore section of the homepage, searchable and ready to be applied by others. Don't forget to ask for compliance for your own projects to show they follow this new standard you just created!

Evolve an existent standard

Soon to be added.

Complying with a standard

Soon to be added.