Feedback and contributions are very welcome!
Here's help on how to make contributions, divided into the following sections:
- general information,
- documentation changes,
- code changes, and
- keeping up with external changes.
For specific proposals, please provide them as
pull requests
or
issues
via our
GitHub site.
For general discussion, feel free to use
Pull requests are preferred, since they are specific. For more about how to create a pull request, see https://help.github.com/articles/using-pull-requests/.
We recommend creating different branches for different (logical) changes, and creating a pull request when you're done into the master branch. See the GitHub documentation on creating branches and using pull requests.
We use GitHub to track proposed changes via its issue tracker and pull requests. Specific changes are proposed using those mechanisms. Issues are assigned to an individual, who works it and then marks it complete. If there are questions or objections, the conversation area of that issue or pull request is used to resolve it.
Our policy is that at least 50% of all proposed modifications will be reviewed before release by a person other than the author, to determine if it is a worthwhile modification and free of known issues which would argue against its inclusion (per the Gold requirement two_person_review).
We achieve this by splitting proposals into two kinds:
- Low-risk modifications. These modifications are being proposed by people authorized to commit directly, pass all tests, and are unlikely to have problems. These include documentation/text updates (other than changes to the criteria) and/or updates to existing gems (especially minor updates) where no risk (such as a security risk) have been identified. The project lead can decide that any particular modification is low-risk.
- Other modifications. These other modifications need to be reviewed by someone else or the project lead can decide to accept the modification. Typically this is done by creating a branch and a pull request so that it can be reviewed before accepting it.
All contributions must agree to the SKALE Network Contributor License Agreement. This is derived from Apache Software Foundations’ Individual Contributor License Agreement v2.0, and it's purpose is to ensure that the guardian of a project's outputs has the necessary ownership or grants of rights over all contributions to allow them to distribute under the chosen license.
Simply submitting a contribution implies this agreement, however, for a pull request to be accepted, you must use the SKALE Network CLA assistant, which is one of the requirement for pull request checks.
All (new) contributed material must be released
under the AGPL-3.0-only license, with exception to material included
under the third_party directory.
All new contributed material
that is not executable, including all text when not executed,
is also released under the
Creative Commons Attribution 4.0 International (CC BY 4.0) license or later.
In general we try to be proactive to detect and eliminate mistakes and vulnerabilities as soon as possible, and to reduce their impact when they do happen. We use a defensive design and coding style to reduce the likelihood of mistakes, a variety of tools that try to detect mistakes early, and an automatic test suite with significant coverage. We also release the software as open source software so others can review it.
Since early detection and impact reduction can never be perfect, we also try to detect and repair problems during deployment as quickly as possible. This is especially true for security issues; see our security information for more.
Please do not use or include trailing whitespace (spaces or tabs at the end of a line). Since they are often not visible, they can cause silent problems and misleading unexpected changes. For example, some editors (e.g., Atom) quietly delete them by default.
Most of the documentation is in "markdown" or "mdx" format. All markdown files use the .md filename extension, otherwise .mdx for mdx files.
Where reasonable, limit yourself to Markdown that will be accepted by different markdown processors (e.g., what is specified by CommonMark or the original Markdown) In practice we use the version of Markdown implemented by GitHub when it renders .md files, and you can use its extensions (in particular, mark code snippets with the programming language used). This version of markdown is sometimes called GitHub-flavored markdown. In particular, blank lines separate paragraphs; newlines inside a paragraph do not force a line break. Beware - this is not the same markdown algorithm used by GitHub when it renders issue or pull comments; in those cases newlines in paragraph-like content are considered as real line breaks; unfortunately this other algorithm is also called GitHub rendered markdown. (Yes, it'd be better if there were standard different names for different things.)
Do not use trailing two spaces for line breaks, since these cannot be seen and may be silently removed by some tools. Instead, use <br /> (an HTML break).
The code style is defined by .clang-format, and in general, all C++ files
should follow it. Files with minor deviations from the defined style are still
accepted in PRs; however, unless explicitly marked with // clang-format off
and // clang-format on, these deviations will be rectified any commit soon
after.
Exercise the principle of least privilege where reasonable and appropriate. Prefer less-coupled cohesive code.
Checking the code on at least one configuration is essential; if you only have a hasty fix that doesn't even compile, better make an issue and put a link to your commit into it (with an explanation what it is about and why).
We strongly recommend using clang-format or, even better, use an IDE that supports it. This will lay a tedious task of following the assumed code style from your shoulders over to your computer.
The installer adds a git remote named 'upstream'. Running 'git pull upstream master' will pull the current version from upstream, enabling you to sync with upstream.
You can reset this, if something has happened to it, using:
git remote add upstream \
https://github.com/skalenetwork/libBLS.gitThis text is based on CONTRIBUTING.md from CII Best Practices Badge project, which is a collective work of its contributors (many thanks!). The text itself is licensed under CC-BY-4.0.