From bdec515ee28aec4a259c14ffa4e5abf97ccf0b23 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Sun, 19 Jul 2020 15:04:22 +0100 Subject: [PATCH] Contributing.md: We're now using Semantic Version strings. * Add/correct links to Releasing.md. * Pre-releases must have tags of the correct form now. * Misc formatting changes, mostly adding a
between sections. --- Contributing.md | 55 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 13 deletions(-) diff --git a/Contributing.md b/Contributing.md index 1832fb3c..7e5423ab 100644 --- a/Contributing.md +++ b/Contributing.md @@ -16,10 +16,12 @@ There is sometimes a misconception that Open Source means that the primary proje That is not so. While you are 100% free to make changes in your own fork, we will only accept changes that are consistent with our vision for EDMC. Fundamental changes in particular need to be agreed in advance. +--- + Version conventions --- -Please see [docs/Releasing.md#Version-Strings] for a description of the -currently used version strings. +Please see [docs/Releasing.md#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`, @@ -31,17 +33,19 @@ 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](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Releasing.md#distribution). +of [the release process](docs/Releasing.md#distribution). + +--- Git branch structure and tag conventions ---- +=== Somewhat based on git-flow, but our particular take on it: ### Branches * `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.D` tag! +code then use the appropriate `Release/A.B.C` tag! * `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 @@ -73,17 +77,30 @@ made. ### Tags #### Stable Releases -All stable releases **MUST** had a tag of the form `Release/A.B.C.D` on the -commit that was `HEAD` when the installer for it was built. +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 -Currently the tags for pre-releases are of the same form as those for stable -releases. This will change in the future when the project for [full semantic -versioning](https://github.com/EDCD/EDMarketConnector/projects/4) is completed. +Tags for pre-releases should be of one of two forms, following [Version + Strings](docs/Releasing.md#version-strings) conventions. -This does mean that some care should be taken. If the current stable - release is `4.0.1.0` then you should 'guess' at the pre-release version -needing to be either `4.1.0.0` or `5.0.0.0` depending on what has changed. +* Initial beta releases should have versions of the form: + + `Major.Minor.Patch-beta` + + with the `` starting with `1` and incrementing with each new beta + pre-release. + +* Release candidates should have versions of the form: + + `Major.Minor.Patch-rc` + + with the `` starting with `1` and incrementing with each new + release candidate. + +The tag should thus be `Release/Major.Minor.Patch-(beta|rc)`. + +The Semantic Versioning `+` should never be a part of the tag. --- @@ -114,6 +131,8 @@ 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. +--- + General workflow --- @@ -133,6 +152,8 @@ will be reflected in the Pull Request*. Ensure that *only* the changes for the 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 === * Adhere to the spelling conventions of the libraries and modules used in the project. Yes, this means using 'color' @@ -154,6 +175,8 @@ Coding Conventions * Going forwards please do place [type hints](https://docs.python.org/3/library/typing.html) on the declarations of your functions, both their arguments and return types. +--- + Git commit conventions === * Please use the standard Git convention of a short title in the first line and fuller body text in subsequent lines. @@ -163,17 +186,23 @@ Git commit conventions * If in doubt, lean towards many small commits. This makes git bisect much more useful. * Please try at all costs to avoid a "mixed-up" commit, i.e. one that addresses more than one issue at once. One thing at a time is best. + +--- Build process === See [Releasing.md](docs/Releasing.md) for the environment and procedure necessary for building the application into a .exe and Windows installer file. +--- + Translations === See [Translations.md](docs/Translations.md) for how to ensure any new phrases your code adds can be easily translated. +--- + Acknowledgement --- The overall structure, and some of the contents, of this document were taken from the [EDDI Contributing.md](https://github.com/EDCD/EDDI/blob/develop/docs/Contributing.md).