GitLab Commit is coming up on August 3-4. Learn how to innovate together using GitLab, the DevOps platform. Register for free: gitlabcommitvirtual2021.com

contrib-guidelines.rst 2.87 KB
Newer Older
1

2
3
4
Contributing to the SKA
***********************

vla22's avatar
vla22 committed
5
We're delighted that you'd like to contribute to an SKA project. First of all, please read our :doc:`/policies/code-of-conduct`, which sets out our expectations for behaviour when working on the SKA. Since you're most likely here to work with our repositories, you should probably read our guide to :doc:`/tools/git`. 
vla22's avatar
vla22 committed
6

vla22's avatar
vla22 committed
7
The advice provided here is general; please look at the documentation for the repository you wish to commit to to check out the specific policies. For example, if you wish to :doc:`/contributor/contribute`, you'll need to read the linked page. If a specific policy contradicts the general advice, please follow the policy for the relevant repository over the guidance provided here. Note that at the moment, not all repositories have good processes to deal with merge requests from forks of that repo. 
vla22's avatar
vla22 committed
8

9
10
SKA repositories follow feature based :ref:`branching-policy` with Merge Request for code review and integration. Everyone is welcome to clone/fork the repository and open a Merge Request for contribution. The Merge request will be reviewed by the repository maintainers. Please make sure you follow the contribution guidelines defined here and in the repository as well.

vla22's avatar
vla22 committed
11
12
Please read the :doc:`/tools/codeguides` for the language you're working with; you'll need to adhere to those standards. Many repositories will perform PEP-8 or similar linting checks. If you're working on documentation for any repository, we use ReadtheDocs, using the Sphinx documentation generator, which uses `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#>`_. 

vla22's avatar
vla22 committed
13
For documentation, we recommend that file and directory names do *not* use underscores, but use hyphens. We recommend using Thomas Cokelaer's `heading syntax <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#headings>`_. We suggest updating pages as you work on them to adopt this style. 
vla22's avatar
vla22 committed
14

vla22's avatar
vla22 committed
15
16
When you are writing instructions for a developer or user, do not assume you know the gender of that person. Pronouns such as "you", "we" and "they" are all acceptable. If you need to refer to the actions of an individual, use singular "they" or a role: "If a team member is struggling with using git, they should contact the System Team for help." But you may find that (as in this sentence), you can write a more friendly guideline by using "you".  

vla22's avatar
vla22 committed
17
Any images you add to documentation should have adequate contrast. A good test is to preview or print images out in black and white; if they're still legible, the contrast is likely to be acceptable for people with low vision. All images should have alt-text added, unless the same information can be obtained from a figure caption. We recommend reading a `guide to writing good alt-text <https://brailleworks.com/how-to-write-amazing-alt-text/>`_.
vla22's avatar
vla22 committed
18
19

Thank you for reading; we hope that you're able to contribute to the SKA.