Documenting your contribution
Documentation is vital to any project. Without it how would anyone know how to use it? This is why, if you make changes that require modifying the documentation, you must update the docs as well.
What changes need documenting
Whilst this is not an extensive list of what changes would need documenting, it should give you an idea of what types of changes would need docs. If you are still unsure then feel free to ask a question on the SMRC-help Gitter channel or send an email to firstname.lastname@example.org. You could also add a comment on your initial issue but it will probably take longer for you to get a response. The sort of changes that would require documentation changes are:
Class method or property changes
User interface changes
Creating a documentation pull request
This is only relevant for creating pull requests for documentation modifications created as a result of pull requests in other repositories. This does not cover creating ordinary pull requests. See the Pull Request Guidelines for more information on creating normal pull requests.
When you make contributions to the project, you may have to update the
projects documentation. To do this you will need to open a separate pull
request in the
Sidings Media Railway Controller repository. This
pull request does not have to follow the same standards as stipulated in
Pull Request Guidelines. Instead you should follow the
formatting standards below.
Naming your PR
In your PR title you should include the name and pull request number of the PR which this documentation links to in the following format:
[PR]: SidingsMedia/<repo>#<pr number>
This helps us track which documentation is about which contribution.
[PR] prefix, this helps us differentiate a contribution
pull request from the general
[BUG] which can also
appear in the docs repository. These two prefixes are used for when a PR
does not relate to a contribution in another repository.
Describing your PR
You should give a short description of what you have changed. There is no need to repeat what you put in your contribution PR here, all we need is a short description of what you have changed or added. You should also add a link to the PR in the other repo here as well. You should check out linking pull requests from other issues for more information on how to do this.
As with all other pull requests, you must make sure that your PR does
not break any checks. The most common issue you will have with breaking
the checks is if you have misspelled any words in your documentation. It
may be that you have actually misspelled some words in which case you
should go back and fix your errors, you can see which words are marked
as incorrect by viewing the workflow output. It may be the case that
the words marked as errors are not errors but technical language that is
not included in the standard dictionaries. In this case you should add
the word to one of the dictionary files in the
You may also run into issues with reuse compliance. This just means that you have not added the correct licence descriptors to each file. To find out how to do this you should consult the reuse spec for more details on how to make a file reuse compliant.