From 6a890188bca9c3f2b0ea4c8a993894d112a8aad0 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 13 Jul 2020 13:38:12 +0100 Subject: [PATCH 1/4] Contributing.md: `master` is deprecated, use `main`. --- Contributing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 4b864cba..5868b69c 100644 --- a/Contributing.md +++ b/Contributing.md @@ -31,7 +31,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/main/docs/Releasing.md#distribution). Git branch structure and tag conventions --- @@ -53,6 +53,8 @@ then the HEAD of this Branch should always point to the code that was used in th This branch should contain anything from `develop` that is considered well tested and ready for the next `stable` merge. +* `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` - 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 From f95e55d3d4b258efc25e791d09c8c685c4b14563 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 13 Jul 2020 13:40:34 +0100 Subject: [PATCH 2/4] Contributing.md: beta can lag behind main/stable/develop --- Contributing.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Contributing.md b/Contributing.md index 5868b69c..bb50b7d6 100644 --- a/Contributing.md +++ b/Contributing.md @@ -39,8 +39,11 @@ 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. +* `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. *This means + that if there hasn't yet been a new beta version this could be far behind + all of: main, develop, stable.* * `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 From 0d045d54f4702e08724e643a288ee7df9fb0737c Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 13 Jul 2020 17:46:57 +0100 Subject: [PATCH 3/4] docs/Releasing.md: re-structure and clarifications. I'd been deviating slightly from what it said, so I've updated to what I now actually do. --- docs/Releasing.md | 150 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 114 insertions(+), 36 deletions(-) diff --git a/docs/Releasing.md b/docs/Releasing.md index eab77da0..8041183a 100644 --- a/docs/Releasing.md +++ b/docs/Releasing.md @@ -51,7 +51,8 @@ There are other things that you should probably change, but can get away with le 1. applongname: The long appname, e.g. 'E:D Market Connector' 1. appcmdname: The CLI appname, e.g. 'EDMC' 1. appversion: The current version, e.g. '3.5.0.0' - 1. update_feed: The URL where the application looks for current latest version information. This URL should be hosting a renamed (so the full URL doesn't change over application versions) version of the appcast_win_.xml file. The original upstream value is `https://marginal.org.uk/edmarketconnector.xml` + 1. update_feed: The URL where the application looks for current latest + version information. This URL should be hosting a renamed (so the full URL doesn't change over application versions) version of the appcast_win_.xml file. The original upstream value is `https://raw.githubusercontent.com/EDCD/EDMarketConnector/releases/edmarketconnector.xml`. Pre-Packaging Steps === @@ -62,11 +63,68 @@ Before you create a new install each time you should: 1. Run `coriolis.py` to update `modules.p` and `ships.p` 1. XXX: Test ? 1. Ensure translations are up to date, see [Translations.md](Translations.md). -1. Increase `appversion` in `config.py` to reflect the changes. See ['Version conventions' in Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#version-conventions). + +Preparing to Package +=== + +**Version numbers should always be referred to in full, e.g. A.B.C.D not the +old A.BC scheme.** + +We'll use an old version number, 3.5.0.0, as an example throughout the +following. + +1. You should by this time know what changes are going into the release, and +which branch (stable or beta) you'll be ultimately updating. +1. So as to make backing out any mistakes easier create a new branch for this +release, using a name like `release-3.5.0.0`. Do not use the tag +`Release/3.5.0.0` form, that could cause confusion. + 1. `git checkout stable` # Or whichever other branch is appropriate. + 1. `git pull origin` # Ensures local branch is up to date. + 1. `git checkout -b release-3.5.0.0` + +1. Get all the relevant code changes into this branch. This might mean +merging from another branch, such as an issue-specific one, or possibly +cherry-picking commits. See [Contributing Guidelines](docs/Contributing.md) +for how such branches should be named. + +1. You should have already decided on the new version number, as it's specified +in `config.py`. You'll need to redo the `.msi` build if you forgot. **Remember +to do a fresh git commit for this change.** + + See ['Version conventions' in Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#version-conventions). + +1. Prepare a changelog text for the release. You'll need this both for the +GitHub release and the contents of the `edmarketconnector.xml` file if making +a `stable` release, as well as any social media posts you make. + 1. The primary location of the changelog is [Changelog.md](Changelog.md) - + update this first. + 1. To be sure you include all the changes look at the git log since the + prior appropriate (pre-)release. + 1. **Only if making a `stable` release.** Update `edmarketconnector.xml` to + add this changelog text to the correct section(s). + 1. Use the following to generate HTML from the MarkDown (`pip + install grip` first if you need to): + + grip ChangeLog.md --export ChangeLog.html + 1. If there's still a Mac OS section scroll down past it to the Windows + section. + 1. You'll need to change the `` and `<description>` texts to + reflect the latest version and the additional changelog. + 1. Update the `url`, `sparkle:version` and `length` elements of the + `<enclosure>` section as per the latest `EDMarketConnector_win_<version>.msi` + file generated by the build process. + 1. As you're working in a version-specific branch, `release-3.5.0.0`, you + can safely commit these changes and push to GitHub. + **Do not merge the branch with `releases` until the GitHub release is in + place.** + +If you're wondering, you needed to get the changelog prepared before building +the .exe and .msi because ChangeLog.md is bundled with the install. Packaging & Installer Generation --- -You'll want to do the .exe and .msi generation in a `cmd.exe` window, not e.g. a 'Git bash' window. +You'll want to do the .exe and .msi generation in a `cmd.exe` window, not e.g. +a 'Git bash' window. The 'Terminal' tab of PyCharm works fine. Assuming the correct python.exe is associated with .py files then simply run: @@ -101,56 +159,76 @@ Output will be something like (`...` denoting parts elided for brevity): Done -You should now have one new/updated folder `dist.win32` and two new files (version number dependent): `EDMarketConnector_win_3.5.0.0.msi` and `appcast_win_3.5.0.0.xml`. If you want to just check the generated .exe files then they're in that `dist.win32` folder. +**Do check the output** for things like not properly specifying extra files +to be included in the install. If they're not picked up by current rules in +`setup.py` then you will need to add them to the `win32` `DATA_FILES` array. -Now check that the `EDMarketConnector.exe` in the `dist.win32` folder does run without errors. +You should now have one new/updated folder `dist.win32` and two new files +(version number dependent): `EDMarketConnector_win_3.5.0.0.msi` and +`appcast_win_3.5.0.0.xml`. -Finally, uninstall your current version of ED Market Connector and re-install using the newly generated .msi file. Check the resulting installation does work (the installer will run the program for you). +Now check that the `EDMarketConnector.exe` in the `dist.win32` folder does run +without errors. + +Finally, uninstall your current version of ED Market Connector and re-install +using the newly generated `EDMarketConnector_win_3.5.0.0.msi` file. Check the +resulting installation does work (the installer will run the program for you). Distribution --- -It is recommended to keep all the files for distribution on github, including the 'update_feed' file. So once you have tested the new .msi file +Once you have tested the new .msi file: -**Version numbers should always be referred to in full, e.g. A.B.C.D not the old A.BC scheme.** +1. Add a git tag for the release, which you'll refer to when actually creating +the release: + 1. This should be named `Release/A.B.C.D`, e.g. `Release/3.5.0.0.` as per + the version number. -We'll use an old version number, 3.5.0.0, as an example throughout the following. +1. Now push the release-specific branch to GitHub. + 1. Check which of your remotes is for github with `git remotes -v`. It + should really be `origin` and the following assumes that. + 1. `git push --set-upstream --tags origin release-3.5.0.0` -1. You should have already decided on the new version number, as it's specified in `config.py`. You'll need to redo the `.msi` build if you forgot. **Remember to do a fresh git commit for this change.** +1. Merge the release-specific branch into the appropriate `stable` or `beta` +branch. You can either do this locally and push the changes, or do it on +GitHub. You'll want to reference `stable` or `beta` in the next step, *not +the release-3.5.0.0 branch, as it's temporary.* -1. So as to make backing out any mistakes easier create a new branch for this release, using a name like `release-3.5.0.0`. Do not use the tag `Release/3.5.0.0` form, that could cause confusion. Ensure all the relevant commits, and no more than them, are present in this branch. - 1. `git checkout releases` - 1. `git pull origin` # Ensures local `releases` branch is up to date. - 1. `git checkout -b release-3.5.0.0` +1. Craft a [new github Release](https://github.com/EDCD/EDMarketConnector/releases/new), + 1. Use the new tag so as to reference the correct commit, along with the + appropriate `stable` or `beta` branch as the 'Target'. + 1. Use the changelog text you already prepared to fill in the 'Release + title' and description. + 1. Attach the `EDMarketConnector_win_<version>.msi` file for Windows (the + Source Code files are added by github based on the release tag). + 1. **If you are making a `beta` or otherwise pre-release you MUST tick the + `[ ] This is a pre-release` box.** Not doing so will cause this release + to be point to by the 'latest' URL. -Now get all the relevant code changes into this branch. This might mean merging from another branch, such as an issue-specific one, or possibly cherry-picking commits. See [Contributing Guidelines](docs/Contributing.md) for how such branches should be named. +1. **Check that the URL for the release that you specified in +`edmarketconnector.xml` actually matches where github has placed the `EDMarketConnector_win_<version>.msi` +file.** If, for instance, you fail to *update* this URL then upon running the +'new' installer it will silently fail, because you made people try to install +the old version over the old version. -**Remember to import any new/updated translations.** See [docs/Translations](docs/Translations) for details. - -1. Prepare a changelog text for the release. You'll need this both for the GitHub release and the contents of the `edmarketconnector.xml` file. - 1. The primary location of the changelog is [Changelog.md](Changelog.md) - update this first. - 1. Update `edmarketconnector.xml` to add this changelog text to the correct section(s). - 1. You'll need to change the `<title>` and `<description>` texts to reflect the latest version and the additional changelog. - 1. Update the `url`, `sparkle:version` and `length` elements of the `<enclosure>` section as per the latest `appcast_win_<version>.xml` file generated by the build process. - 1. As you're working in a version-specific branch, `release-3.5.0.0`, you can safely commit these changes to git. **Do not merge the branch with `releases` until the github release is in place.** - -1. Add a git tag for the release, which you'll refer to when actually creating the release: - 1. This should be named `Release/A.B.C.D`, e.g. `Release/3.5.0.0.` as per the version number. - -1. Now push this release-specific branch to GitHub. - 1. Check which of your remotes is for github with `git remotes -v`. It should really be `origin` and the following assumes that. - 1. `git push --set-upstream --tags origin release-A.B.C.D` - -1. Craft a [new github Release](https://github.com/EDCD/EDMarketConnector/releases/new), using the new tag so as to reference the correct commit. Include the .msi file for Windows (the Source Code files are added by github based on the release tag). Use the changelog text you already prepared. - -1. **Check that the URL for the release that you specified in `edmarketconnector.xml` actually matches where github has placed the `.msi` file.** If, for instance, you fail to *update* this URL then upon running the 'new' installer it will silently fail, because you made people try to install the old version over the old version. + Fix it if needs be and make a new commit. It's only in the `edmarketconnector.xml` + file so no need to redo the build. As this file is only important in the + `releases` branch you also don't need to redo the GitHub release, i.e. + the release tag doesn't need updating to point to this new commit. 1. **Now merge the new release branch into `releases`.** -The final step below is what fully publishes the release for running EDMC instances to pick up on 'Check for Updates'. The WinSparkle check for updates specifically targets `https://raw.githubusercontent.com/EDCD/EDMarketConnector/releases/edmarketconnector.xml` as per `config.py `update_feed`. +This is the final step that fully publishes the release for running +EDMC instances to pick up on 'Check for Updates'. The WinSparkle check for +updates specifically targets `https://raw.githubusercontent.com/EDCD/EDMarketConnector/releases/edmarketconnector.xml` +as per `config.py` `update_feed`. 1. `git checkout releases` 1. `git merge release-3.5.0.0` 1. `git push origin` + + (Or merge on GitHub). + + NB: It can take some time for GitHub to show the changed + edmarketconnector.xml contents to all users. -1. You should also merge the code into the `stable` branch for easy reference. Pre-Releases === From c51ba1c445d6a5bf686cefe5e99f4f3a2e7541cb Mon Sep 17 00:00:00 2001 From: Athanasius <github@miggy.org> Date: Wed, 15 Jul 2020 10:43:30 +0100 Subject: [PATCH 4/4] Clarify what stable and beta branches may contain. Describe release tags. * Both `stable` and `beta` might contain extra commits for hotfixes beyond what is currently released. * Describe the Stable Release tag form, and point out that currently the pre-release tag form is the same. --- Contributing.md | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/Contributing.md b/Contributing.md index bb50b7d6..0bc0a4a8 100644 --- a/Contributing.md +++ b/Contributing.md @@ -37,13 +37,19 @@ Git branch structure and tag conventions --- 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. +### 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! * `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. *This means - that if there hasn't yet been a new beta version this could be far behind - all of: main, develop, stable.* + just a branch to be run from source*, then this branch will contain that + code. As per `stable` above, this branch might be ahead of the latest + pre-release due to merging of hotfixes. Use the appropriate tag if you want + 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` - 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 @@ -64,6 +70,23 @@ 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** had a tag of the form `Release/A.B.C.D` 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. + +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. + +--- + 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.