Before pushing new changes, ensure they don't produce linting errors. Commit any
files that were corrected.
Please ensure your changes match the cosmetic style of the existing project,
Please ensure your changes match the cosmetic style of the existing project,
and **never** mix cosmetic and functional changes in the same commit, as it
and **never** mix cosmetic and functional changes in the same commit, as it
makes it horribly hard to review otherwise.
makes it horribly hard to review otherwise.
Before doing a commit, ensure the changes you've made don't produce
linting errors. You can do this by running the linters as follows. Ensure to
commit any files that were corrected.
::
# Install the dependencies
pip install -U black flake8 isort
# Run the linter script
./scripts-dev/lint.sh
Changelog
## Changelog
~~~~~~~~~
All changes, even minor ones, need a corresponding changelog / newsfragment
All changes, even minor ones, need a corresponding changelog / newsfragment
entry. These are managed by Towncrier
entry. These are managed by [Towncrier](https://github.com/hawkowl/towncrier).
(https://github.com/hawkowl/towncrier).
To create a changelog entry, make a new file in the ``changelog.d`` file named
To create a changelog entry, make a new file in the `changelog.d` directory named
in the format of ``PRnumber.type``. The type can be one of the following:
in the format of `PRnumber.type`. The type can be one of the following:
* ``feature``.
*`feature`
* ``bugfix``.
*`bugfix`
* ``docker`` (for updates to the Docker image).
*`docker` (for updates to the Docker image)
* ``doc`` (for updates to the documentation).
*`doc` (for updates to the documentation)
* ``removal`` (also used for deprecations).
*`removal` (also used for deprecations)
* ``misc`` (for internal-only changes).
*`misc` (for internal-only changes)
The content of the file is your changelog entry, which should be a short
The content of the file is your changelog entry, which should be a short
description of your change in the same style as the rest of our `changelog
description of your change in the same style as the rest of our [changelog](
<https://github.com/matrix-org/synapse/blob/master/CHANGES.md>`_. The file can
https://github.com/matrix-org/synapse/blob/master/CHANGES.md). The file can
contain Markdown formatting, and should end with a full stop ('.') for
contain Markdown formatting, and should end with a full stop ('.') for
consistency.
consistency.
...
@@ -108,20 +108,21 @@ Adding credits to the changelog is encouraged, we value your
...
@@ -108,20 +108,21 @@ Adding credits to the changelog is encouraged, we value your
contributions and would like to have you shouted out in the release notes!
contributions and would like to have you shouted out in the release notes!
For example, a fix in PR #1234 would have its changelog entry in
For example, a fix in PR #1234 would have its changelog entry in
``changelog.d/1234.bugfix``, and contain content like "The security levels of
`changelog.d/1234.bugfix`, and contain content like "The security levels of
Florbs are now validated when recieved over federation. Contributed by Jane
Florbs are now validated when received over federation. Contributed by Jane
Matrix.".
Matrix.".
Debian changelog
## Debian changelog
----------------
Changes which affect the debian packaging files (in ``debian``) are an
Changes which affect the debian packaging files (in `debian`) are an
exception.
exception.
In this case, you will need to add an entry to the debian changelog for the
In this case, you will need to add an entry to the debian changelog for the
next release. For this, run the following command::
next release. For this, run the following command:
dch
```
dch
```
This will make up a new version number (if there isn't already an unreleased
This will make up a new version number (if there isn't already an unreleased
version in flight), and open an editor where you can add a new changelog entry.
version in flight), and open an editor where you can add a new changelog entry.
...
@@ -133,74 +134,77 @@ directory, you will need both a regular newsfragment *and* an entry in the
...
@@ -133,74 +134,77 @@ directory, you will need both a regular newsfragment *and* an entry in the
debian changelog. (Though typically such changes should be submitted as two
debian changelog. (Though typically such changes should be submitted as two
separate pull requests.)
separate pull requests.)
Sign off
## Sign off
~~~~~~~~
In order to have a concrete record that your contribution is intentional
In order to have a concrete record that your contribution is intentional
and you agree to license it under the same terms as the project's license, we've adopted the
and you agree to license it under the same terms as the project's license, we've adopted the
same lightweight approach that the Linux Kernel
same lightweight approach that the Linux Kernel
`submitting patches process <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_, Docker
[submitting patches process](
(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
