From 6328c47a41c8780fde84f49b9bdbe4dca99ddf5b Mon Sep 17 00:00:00 2001 From: Athanasius Date: Tue, 10 Aug 2021 14:59:34 +0100 Subject: [PATCH] Docs: Update Releasing.md and Automatic-Builds.md for using auto-builds We now prefer automatic builds, triggered off our normal `Release/` tags being pushed. --- docs/Automatic Builds.md | 42 +++++++---- docs/Releasing.md | 157 +++++++++++++++++++++++---------------- 2 files changed, 121 insertions(+), 78 deletions(-) diff --git a/docs/Automatic Builds.md b/docs/Automatic Builds.md index 11932c50..e709e79b 100644 --- a/docs/Automatic Builds.md +++ b/docs/Automatic Builds.md @@ -1,12 +1,36 @@ # Introduction -Instead of building manually as laid out by [Releasing](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Releasing.md), you can build the EDMC installer using GitHub actions. +Instead of building manually as laid out by +[Releasing](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Releasing.md), +you can build the EDMarketConnector installer using GitHub actions. ## Initiating a workflow run -Starting a workflow run is done from the Actions tab at the top of the main GitHub UI +### Automatically on tag push +Once you are sure you have a branch all ready for release as a new version you +should be adding a `Release/` tag at that HEAD. Pushing +such a tag to GitHub will cause the +[the GitHub Windows Build Action file](../.github/workflows/windows-build.yml) +to build an installer and create a draft release, with the pre-release box +pre-ticked. This ensures you don't accidentally create a new non-pre +release which will always become the target of the `latest` shortcut on GitHub. -NB: The branch you want to build must have the workflow file (`.github/workflows/windows-build.yml`), and the version of the file in that branch is the version that will be used for the build (e.g. for different python versions) +You can monitor such an auto-build from the Actions tab on GitHub. If it +completes successfully then check the Releases tab on GitHub for the draft +that was created. + +See [Releasing.md#Distribution](./Releasing.md#distribution) for details on +how to fully publish an automatic release so that running EDMarketConnector.exe +clients pick it up as an update. + +### Manually +Starting a workflow run is done from the Actions tab at the top of the main +GitHub UI + +NB: The branch you want to build must have the workflow file +(`.github/workflows/windows-build.yml`), and the version of the file in that +branch is the version that will be used for the build (e.g. for different +python versions) 1. Select the Actions tab at the top of the main GitHub interface 2. Select the `Build EDMC for Windows` workflow on the left @@ -16,7 +40,8 @@ NB: The branch you want to build must have the workflow file (`.github/workflows ## Downloading built installer files -When the workflow is (successfully) completed, it will upload the msi file it built as a "Workflow Artifact". You can find the artifacts as follows: +When the workflow is (successfully) completed, it will upload the msi file it +built as a "Workflow Artifact". You can find the artifacts as follows: 1. Select `All workflows` on the left 2. Select the `Build EDMC for Windows` action @@ -26,12 +51,3 @@ When the workflow is (successfully) completed, it will upload the msi file it bu Within the `Built Files` zip file is the installer msi **Please ensure you test the built msi before creating a release.** - -## Automatic release creation - -Github Actions can automatically create a release after finishing a build (as mentioned above). To make this happen, -simply push a tag to the repo with the format `v1.2.3` where 1.2.3 is the semver for the version (Note that this is -**DISTINCT** from the normal `Release/1.2.3` format for release tags). - -Once the push is completed, a build will start, and once that is complete, a draft release will be created. Edit the -release as needed and publish it. **Note that you should still test the built msi before publishing the release** diff --git a/docs/Releasing.md b/docs/Releasing.md index 3ef5d443..e96f4740 100644 --- a/docs/Releasing.md +++ b/docs/Releasing.md @@ -1,6 +1,15 @@ # Introduction -This document aims to enable anyone to quickly get up to speed on how to: +Builds can, **and must in normal operation** be run automatically from GitHub +Actions. For more information on that process +see [Automatic Builds](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Automatic%20Builds.md). +This allows us to state that the files we distribute never touched anything +but GitHub servers before a user downloaded them, which means no +possibility of malware on a developer's machine infecting the resulting files. + +Obviously you might still need to run a manual build on your own hardware +in order to test changes and/or diagnose build issues. As such +this document aims to enable anyone to quickly get up to speed on how to: 1. Build a Windows .exe for the application 1. Package that .exe into an .msi file for distribution @@ -10,7 +19,6 @@ This document aims to enable anyone to quickly get up to speed on how to: Note that for Windows only a 32-bit application is supported at this time. This is principally due to the Windows Registry handling in config.py. -Builds can be run automatically from GitHub Actions. For more information on that process, see [Automatic Builds](https://github.com/EDCD/EDMarketConnector/blob/main/docs/Automatic%20Builds.md). # Environment @@ -96,16 +104,16 @@ that. 1. Application names, version and URL of the file with latest release information. These are all in the `config.py` file. See the `from config import ...` lines in setup.py. - 1. `appname`: The short appname, e.g. 'EDMarketConnector' - 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. `4.0.2`. **You MUST make - this something like `4.0.2+` to differentiate it from + 1. `appname`: The short appname, e.g. 'EDMarketConnector' + 2. `applongname`: The long appname, e.g. 'E:D Market Connector' + 3. `appcmdname`: The CLI appname, e.g. 'EDMC' + 4. `_static_appversion`: The current version, e.g. `4.0.2`. **You MUST + make this something like `4.0.2+` to differentiate it from upstream.** Whatever is in this field is what will be reported if sending messages to EDDN, or any of the third-party website APIs. This is utilising the 'build metadata' part of a Semantic version. - 1. `copyright`: The Copyright string. - 1. `update_feed`: The URL where the application looks for current latest + 5. `copyright`: The Copyright string. + 6. `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 @@ -214,19 +222,6 @@ a `stable` release, as well as any social media posts you make. 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` and `sparkle:version` elements of the `<enclosure>` - section. **NB: Yes, sparkle:version should be the Semantic Version - string, not the Windows A.B.C.D form.** 1. As you're working in a version-specific branch, `release-4.0.2`, you can safely commit these changes and push to GitHub. **Do not merge the branch with `releases` until the GitHub release is in place.** @@ -304,61 +299,92 @@ The git commit for this should end up being the release tag as below. # Distribution -Once you have tested the new .msi file: +Whether you built it manually or automatically you **MUST** test the `.msi` +installer file prior to making the release live. + +Once that is done then for manually built installers: 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`, e.g. `Release/4.0.2.` as per - the version string. + the release: + 1. This should be named `Release/A.B.C`, e.g. `Release/4.0.2.` as per + the version string. -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-4.0.2` + **Do NOT add this tag until you're sure you're ready. Pushing a tag to + GitHub that matches the pattern `Release/*` (double-check this in + [the GitHub Windows Build Action file](../.github/workflows/windows-build.yml)) + will cause an auto-build and creation of a draft release.** -1. Merge the release-specific branch into the appropriate `stable` or `beta` + Yes, this does mean you should really just be using this auto-build setup + when creating an installer for release to users. You'll at least need to + edit the draft release that it creates, i.e. swap out its `.msi` for the + one that you built. But, **again, you should just be using the auto-build + mechanism**. + +3. 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-4.0.2` + +4. 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-4.0.2 branch, as it's temporary.* -1. Craft a [new github Release](https://github.com/EDCD/EDMarketConnector/releases/new), +5. **You should no longer need to manually create a release, due to + auto-building of any release tag, but you'll probably still need to edit + in the ChangeLog, so...** + + 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 + 2. 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 + 3. 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 + 4. **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. + to be pointed to by the 'latest' URL. + 5. We always create a discussion for any new release, so tick the + `Create a discussion for this release ` box, and check it's targeted at + the `Announcement` category. -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. +Once the release is created, then **only if making a `stable` release** +update `edmarketconnector.xml` **in the `releases` branch only** to add this +changelog text to the correct section(s): +1. `git checkout releases` +2. `git merge stable` - You should have merged the new release branch + into `stable` above. +3. Use the following to generate HTML from the MarkDown (`pip + install grip` first if you need to): - 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. + grip --export ChangeLog.md +4. Open `edmarketconnector.xml` in your editor. +5. If there's still a Mac OS section croll down past it to the Windows + section. +6. You'll need to change the `<title>` and `<description>` texts to + reflect the latest version and the additional changelog. +7. Update the `url` and `sparkle:version` elements of the `<enclosure>` + section. + 1. The `url` needs to match what GitHub created in the Release for the + `.msi` file. Check it! -1. **Now merge the new release branch into `releases`.** -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 + 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. + 3. Yes, `sparkle:version` should be the Semantic Version string, + not the Windows A.B.C.D form. +8. `git push origin` - `https://raw.githubusercontent.com/EDCD/EDMarketConnector/releases/edmarketconnector.xml` - - as per `config.py` `update_feed`. - 1. `git checkout releases` - 1. `git merge release-4.0.2` - 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. + 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`. + + NB: It can take some time for GitHub to show the changed + edmarketconnector.xml contents to all users. **You should now update [Known Issues](https://github.com/EDCD/EDMarketConnector/issues/618) to reflect anything now fixed in latest release.** @@ -367,11 +393,12 @@ to reflect anything now fixed in latest release.** If you are making a pre-release then: -1. **DO NOT** Edit edmarketconnector.xml at all. No, not even if you think you - won't accidentally merge it into `releases`. Just don't change it at all. -1. **DO NOT** merge into `releases`. -1. **DO NOT** merge into `stable`. -1. *Do* merge the code into `beta` after you have made a 'pre-release' on +1. **DO NOT** Edit `edmarketconnector.xml` at all. No, not even if you + think you won't accidentally merge it into `releases`. Just don't change it + at all. +3. **DO NOT** merge into `releases`. +4. **DO NOT** merge into `stable`. +5. *Do* merge the code into `beta` after you have made a 'pre-release' on GitHub. # Changing Python version