From 263010f369c37fe2e8a3008b07ab65c84201cc9b Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Tue, 30 Jun 2020 16:25:08 +0100
Subject: [PATCH 1/3] Adds Contributing.md
* Outlines everything a new contributor should know.
* There's one 'XXX' to-check items with regards to Windows Installer,
and if it does think A.B.C.1 should be installed in place of A.B.C.0.
---
Contributing.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 147 insertions(+)
create mode 100644 Contributing.md
diff --git a/Contributing.md b/Contributing.md
new file mode 100644
index 00000000..517bd849
--- /dev/null
+++ b/Contributing.md
@@ -0,0 +1,147 @@
+Guidelines for contributing to EDMC
+===
+
+Work on Issues
+---
+If you are not part of the core development team then you should only be performing work that addresses an open issue.
+
+So, if what you think needs doing isn't currently referred to in an [open issue](https://github.com/EDCD/EDMarketConnector/issues), then you should first [open an issue](https://github.com/EDCD/EDMarketConnector/issues/new/choose).
+
+Check with us first
+---
+Whilst we welcome all efforts to improve the program it's best to ensure that you're not duplicating, or worse,
+wasting effort.
+
+There is sometimes a misconception that Open Source means that the primary project is obliged to accept Pull Requests.
+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
+---
+The only currently supported format for the version is A.B.C.D, following [Semantic Versioning](https://semver.org/)
+conventions. Note that the 'D' part being different does *not* make the version different for purposes of the
+WinSparkle update checking, XXX (true?): or the Windows installer thinking it's a newer version.
+
+There is currently no support for appending any other string to the version (it will break some of the build
+code), see [this issue](https://github.com/EDCD/EDMarketConnector/issues/534).
+
+Historically the A.B.C.D version was collapsed into A.BC and then a tag added of the form `rel-ABC`. Going
+forwards we will always use the full version and 'folder style' tag names, e.g. `Release/A.B.C.D` .
+
+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/master/docs/RELEASING.md#distribution).
+
+Git branch structure and tag contentions
+---
+Somewhat based on git-flow, but our particular take on it:
+
+* `stable` - The HEAD of this Branch should always point to the code that was used in the last released stable version.
+
+* `beta` - If we run any pre-release betas *with actual builds released, not just a branch to be run from source*,
+then the HEAD of this Branch should always point to the code that was used in the last beta version.
+
+* `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.
+
+* `master` - To avoid accidental commits that could have unintended consequences we do NOT use this branch.
+ see `develop` or `stable` instead. However, whenever a new stable release is made `master` should be fast-forwarded
+ to remain in sync with `stable`, as this is the default branch for code display on GitHub. Anyone working on
+ something without first reading these guidelines is also likely to have worked on either local `master`
+ directly, or a branch based on it.
+
+* `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,
+but some care will be necessary to ensure no users are left behind (their client checking the `releases` branch which
+then no longer exists). For the time being this should always be kept in sync with `stable` as each new release is
+made.
+
+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
+pick one for the naming scheme below, but mention all in commit messages and the Pull Request.
+
+In all cases the branch should be named as per the scheme `<class>/<issue number>-<title>`:
+* `<class>` - We have several classes of WIP branch:
+ * `fix` - For working on bug fixes, e.g. `fix/184-crash-in-startup`
+ * `enhancement` - For enhancing an *existing* feature, e.g. `enhancement/192-add-thing-to-wotsit`
+ * `feature` - For working on *new* features, e.g. `feature/284-allow-users-to-frob`
+
+* `<issue-number>` is for easy reference when citing the issue number in commit messages.
+* `<title>` is intended to allow anyone to quickly know what the branch is addressing. Try to choose something
+ succinct for `<title>`, it's just there for easy reference, it doesn't need to be the entire title of
+ the appropriate issue.
+
+Which branch you base your work on will depend on which class of WIP it is. If you're fixing a bug in the latest
+`stable` then it's best to base your branch on its HEAD. If it's a fix for a beta release then base off of `beta`'s
+HEAD. If you're working on a new feature then you'd want to base the work on `develop`'s HEAD.
+
+**Important**: Please *under no circumstance* merge *from* the source branch after you have started work in
+your WIP branch. If there are any non-trivial conflicts when we merge your Pull Request then we might ask you
+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
+---
+
+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. 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
+===
+* Adhere to the spelling conventions of the libraries and modules used in the project. Yes, this means using 'color'
+ rather than 'colour', and in general will mean US, not British, spellings.
+* **ALWAYS** place a single-statement control flow body, for control statements such as `if`, `else`, `for`, `foreach`,
+ on a separate line, with consistent indentation.
+
+ Yes:
+
+ if somethingTrue:
+ Things we then do
+
+ No:
+
+ if somethingTrue: One thing we do
+
+ Yes, some existing code still flouts this rule.
+
+* 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.
+* Please reference issue numbers using the "hashtag" format #123 in your commit message wherever possible.
+ This lets GitHub create two-way hyperlinks between the issue report and the commit.
+ Certain text in a PR that fixes an issue can auto-close the issue when the PR is merged.
+* 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).
From 10c0509a113a7bed41defef979370102fe6d0e02 Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Tue, 30 Jun 2020 16:40:40 +0100
Subject: [PATCH 2/3] RELEASING.md doesn't need to shout
---
docs/{RELEASING.md => Releasing.md} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename docs/{RELEASING.md => Releasing.md} (100%)
diff --git a/docs/RELEASING.md b/docs/Releasing.md
similarity index 100%
rename from docs/RELEASING.md
rename to docs/Releasing.md
From 89e78137c33d6a6a296510de781a5c5ef5f560d7 Mon Sep 17 00:00:00 2001
From: Athanasius <github@miggy.org>
Date: Tue, 30 Jun 2020 16:43:10 +0100
Subject: [PATCH 3/3] RELEASING.md is no longer shouted.
---
Contributing.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Contributing.md b/Contributing.md
index 517bd849..9f61b1fa 100644
--- a/Contributing.md
+++ b/Contributing.md
@@ -29,7 +29,7 @@ Historically the A.B.C.D version was collapsed into A.BC and then a tag added of
forwards we will always use the full version and 'folder style' tag names, e.g. `Release/A.B.C.D` .
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/master/docs/RELEASING.md#distribution).
+are another matter handled as part of [the release process](https://github.com/EDCD/EDMarketConnector/blob/master/docs/Releasing.md#distribution).
Git branch structure and tag contentions
---
@@ -134,7 +134,7 @@ Git commit conventions
Build process
===
-See [RELEASING.md](docs/RELEASING.md) for the environment and procedure necessary for building the application into
+See [Releasing.md](docs/Releasing.md) for the environment and procedure necessary for building the application into
a .exe and Windows installer file.
Translations