ED/EDMarketConnector
1
0
Fork 0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-04-15 00:30:33 +03:00
Code Issues Projects Releases Wiki Activity

Contributing: Re-arrange sections more logically

Browse Source 
1. General workflow first.
2. Then branches, including 'work in progress'.
3. Followed by tags.
4. *Then* 'Version conventions'.
This commit is contained in:
Athanasius 2021-06-07 12:18:56 +01:00
parent 9dcb79a5db
commit 3c13e84910
1 changed files with 68 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
Contributing.md
View File

@ -23,22 +23,25 @@ consistent with our vision for EDMC. Fundamental changes in particular need to b
---
## Version conventions
## General workflow
Please see [Version Strings](docs/Releasing.md#version-strings)
for a description of the currently used version strings.
1. You will need a GitHub account.
1. Fork the repository on GitHub into your account there (hereafter referred to as 'your fork').
1. In your local copy of *your* fork create an appropriate WIP branch.
1. Develop the changes, testing as you go (no we don't have any actual tests yet).
1. Be as sure as you can that the code works as you intend and hasn't introduced any other bugs or regressions.
1. Test the codebase as a whole against any unit tests that do exist, and add your own as you can.
1. Check your code against flake8 periodically.
1. When you're sure the work is final:
1. Push your WIP branch to your fork (you probably should have been doing this as you worked as a form of backup).
1. Access the WIP branch on your fork on GitHub and create a Pull Request. Mention any Issue number(s) that it
addresses.
1. Await feedback in the form of comments on the Pull Request.
Historically a `A.BC` form was used, based on an internal `A.B.C.D` version
string. This was changed to simply `A.B.C.D` throughout for `4.0.0.0`,
`4.0.1.0` and `4.0.2.0`. It would also continue for any other increment of
only the 'C' (Patch) component.
Going forwards we will always use the full [Semantic Version](https://semver.org/#semantic-versioning-specification-semver)
and 'folder style' tag names, e.g. `Release/Major.Minor.Patch`.
Currently the only file that defines the version code-wise is `config.py`.
`Changelog.md` and `edmarketconnector.xml` are another matter handled as part
of [the release process](docs/Releasing.md#distribution).
**IMPORTANT**: Once you have created the Pull Request *any changes you make to that WIP branch and push to your fork
will be reflected in the Pull Request*. Ensure that *only* the changes for the issue(s) you are addressing are in
the WIP branch. Any other work should occur in its own separate WIP branch. If needs be make one branch to work in
and another for the Pull Request, merging or cherry-picking commits as needed.
---
@ -46,15 +49,15 @@ of [the release process](docs/Releasing.md#distribution).
Somewhat based on git-flow, but our particular take on it:
## Branches
### Branches
### `stable`
#### `stable`
This will either have `HEAD` pointing to the latest stable release code *or* might have extra code merged in for a
hotfix that will shortly be in the next stable release. If you want the latest stable release code then use the
appropriate `Release/A.B.C` tag!
### `beta`
#### `beta`
If we run any pre-release betas *with actual builds released, not
just a branch to be run from source*, then this branch will contain that
@ -64,13 +67,13 @@ to be sure of the code you checkout.
*If there hasn't yet been a new beta version this could be far behind all
of: `main`, `develop`, `stable`.*
### `develop`
#### `develop`
This is the branch where all current development is integrated. No commits should be made directly
to this as the work should be done in a separate branch used in a Pull Request before being merged as part of
resolving that Pull Request.
### `main`
#### `main`
Yes, we've renamed this from `master`. See
"[Using 'main' as the primary branch in Git](https://github.com/EDCD/EDMarketConnector/wiki/Git-Using-Main-Branch)"
@ -79,11 +82,11 @@ for instructions on ensuring you're cleanly using it in any local clone.
This branch should contain anything from `develop` that is considered well
tested and ready for the next `stable` merge.
### `master`
#### `master`
**This is no longer used. If the branch is even present then it's no longer updated. You should be using `main` instead.**
### `releases`
#### `releases`
Currently the version of the `edmarketconnector.xml` 'appcast' file in this branch is what live
clients check to be notified of new versions. This can potentially be replaced with the `stable` branch's version,
@ -91,39 +94,7 @@ but some care will be necessary to ensure no users are left behind (their client
then no longer exists). For the time being this should always be kept in sync with `stable` as each new release is
made.
## Tags
### Stable Releases
All stable releases **MUST** have a tag of the form `Release/Major.Minor.Patch`
on the commit that was `HEAD` when the installer for it was built.
### Pre-Releases
Tags for pre-releases should be of one of two forms, following [Version
Strings](docs/Releasing.md#version-strings) conventions.
* Initial beta releases should have versions of the form:
`Major.Minor.Patch-beta<serial>`
with the `<serial>` starting with `1` and incrementing with each new beta
pre-release.
* Release candidates should have versions of the form:
`Major.Minor.Patch-rc<serial>`
with the `<serial>` starting with `1` and incrementing with each new
release candidate.
The tag should thus be `Release/Major.Minor.Patch-(beta|rc)<serial>`.
The Semantic Versioning `+<build metadata>` should never be a part of the tag.
---
## Work in progress conventions
### Work in progress conventions
Remember, you should always be working versus a single issue, even if the work is part of a Milestone or Project.
There might be cases where issues aren't duplicates, but your work still addresses more than one. In that case
@ -151,6 +122,57 @@ your WIP branch. If there are any non-trivial conflicts when we merge your Pull
to *rebase* your WIP branch on the latest version of the source branch. Otherwise, we'll work out how to best
merge your changes via comments in the Pull Request.
### Tags
#### Stable Releases
All stable releases **MUST** have a tag of the form `Release/Major.Minor.Patch`
on the commit that was `HEAD` when the installer for it was built.
#### Pre-Releases
Tags for pre-releases should be of one of two forms, following [Version
Strings](docs/Releasing.md#version-strings) conventions.
* Initial beta releases should have versions of the form:
`Major.Minor.Patch-beta<serial>`
with the `<serial>` starting with `1` and incrementing with each new beta
pre-release.
* Release candidates should have versions of the form:
`Major.Minor.Patch-rc<serial>`
with the `<serial>` starting with `1` and incrementing with each new
release candidate.
The tag should thus be `Release/Major.Minor.Patch-(beta|rc)<serial>`.
The Semantic Versioning `+<build metadata>` should never be a part of the tag.
---
## Version conventions
Please see [Version Strings](docs/Releasing.md#version-strings)
for a description of the currently used version strings.
Historically a `A.BC` form was used, based on an internal `A.B.C.D` version
string. This was changed to simply `A.B.C.D` throughout for `4.0.0.0`,
`4.0.1.0` and `4.0.2.0`. It would also continue for any other increment of
only the 'C' (Patch) component.
Going forwards we will always use the full [Semantic Version](https://semver.org/#semantic-versioning-specification-semver)
and 'folder style' tag names, e.g. `Release/Major.Minor.Patch`.
Currently the only file that defines the version code-wise is `config.py`.
`Changelog.md` and `edmarketconnector.xml` are another matter handled as part
of [the release process](docs/Releasing.md#distribution).
---
## Linting
We use flake8 for linting all python source.
@ -193,28 +215,6 @@ Otherwise, see the [pytest documentation](https://docs.pytest.org/en/stable/cont
---
## General workflow
1. You will need a GitHub account.
1. Fork the repository on GitHub into your account there (hereafter referred to as 'your fork').
1. In your local copy of *your* fork create an appropriate WIP branch.
1. Develop the changes, testing as you go (no we don't have any actual tests yet).
1. Be as sure as you can that the code works as you intend and hasn't introduced any other bugs or regressions.
1. Test the codebase as a whole against any unit tests that do exist, and add your own as you can.
1. Check your code against flake8 periodically.
1. When you're sure the work is final:
1. Push your WIP branch to your fork (you probably should have been doing this as you worked as a form of backup).
1. Access the WIP branch on your fork on GitHub and create a Pull Request. Mention any Issue number(s) that it
addresses.
1. Await feedback in the form of comments on the Pull Request.
**IMPORTANT**: Once you have created the Pull Request *any changes you make to that WIP branch and push to your fork
will be reflected in the Pull Request*. Ensure that *only* the changes for the issue(s) you are addressing are in
the WIP branch. Any other work should occur in its own separate WIP branch. If needs be make one branch to work in
and another for the Pull Request, merging or cherry-picking commits as needed.
---
## Coding Conventions
### In general, please follow [PEP8](https://www.python.org/dev/peps/pep-0008/)