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

Docs: Update Releasing.md and Automatic-Builds.md for using auto-builds

Browse Source 
We now prefer automatic builds, triggered off our normal
`Release/<semantic version>` tags being pushed.
This commit is contained in:
Athanasius 2021-08-10 14:59:34 +01:00
parent e37f7bd3bc
commit 6328c47a41
No known key found for this signature in database
GPG Key ID: AE3E527847057C7D
2 changed files with 121 additions and 78 deletions

42
docs/Automatic Builds.md

@ -1,12 +1,36 @@
# Introduction # 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 ## 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/<semantic version>` 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 1. Select the Actions tab at the top of the main GitHub interface
2. Select the `Build EDMC for Windows` workflow on the left 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 ## 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 1. Select `All workflows` on the left
2. Select the `Build EDMC for Windows` action 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 Within the `Built Files` zip file is the installer msi
**Please ensure you test the built msi before creating a release.** **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**

157
docs/Releasing.md

@ -1,6 +1,15 @@
# Introduction # 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. Build a Windows .exe for the application
1. Package that .exe into an .msi file for distribution 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. 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. 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 # Environment
@ -96,16 +104,16 @@ that.
1. Application names, version and URL of the file with latest release 1. Application names, version and URL of the file with latest release
information. These are all in the `config.py` file. See the information. These are all in the `config.py` file. See the
`from config import ...` lines in setup.py. `from config import ...` lines in setup.py.
1. `appname`: The short appname, e.g. 'EDMarketConnector' 1. `appname`: The short appname, e.g. 'EDMarketConnector'
1. `applongname`: The long appname, e.g. 'E:D Market Connector' 2. `applongname`: The long appname, e.g. 'E:D Market Connector'
1. `appcmdname`: The CLI appname, e.g. 'EDMC' 3. `appcmdname`: The CLI appname, e.g. 'EDMC'
1. `appversion`: The current version, e.g. `4.0.2`. **You MUST make 4. `_static_appversion`: The current version, e.g. `4.0.2`. **You MUST
this something like `4.0.2+<myversion>` to differentiate it from make this something like `4.0.2+<myversion>` to differentiate it from
upstream.** Whatever is in this field is what will be reported if upstream.** Whatever is in this field is what will be reported if
sending messages to EDDN, or any of the third-party website APIs. sending messages to EDDN, or any of the third-party website APIs.
This is utilising the 'build metadata' part of a Semantic version. This is utilising the 'build metadata' part of a Semantic version.
1. `copyright`: The Copyright string. 5. `copyright`: The Copyright string.
1. `update_feed`: The URL where the application looks for current latest 6. `update_feed`: The URL where the application looks for current latest
version information. This URL should be hosting a renamed (so the full version information. This URL should be hosting a renamed (so the full
URL doesn't change over application versions) version of the URL doesn't change over application versions) version of the
appcast_win_<version>.xml file. The original upstream value is appcast_win_<version>.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. update this first.
1. To be sure you include all the changes look at the git log since the 1. To be sure you include all the changes look at the git log since the
prior appropriate (pre-)release. 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 `<title>` 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 1. As you're working in a version-specific branch, `release-4.0.2`, you
can safely commit these changes and push to GitHub. can safely commit these changes and push to GitHub.
**Do not merge the branch with `releases` until the GitHub release is in place.** **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 # 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 1. Add a git tag for the release, which you'll refer to when actually creating
the release: the release:
1. This should be named `Release/A.B.C`, e.g. `Release/4.0.2.` as per 1. This should be named `Release/A.B.C`, e.g. `Release/4.0.2.` as per
the version string. the version string.
1. Now push the release-specific branch to GitHub. **Do NOT add this tag until you're sure you're ready. Pushing a tag to
1. Check which of your remotes is for github with `git remotes -v`. It GitHub that matches the pattern `Release/*` (double-check this in
should really be `origin` and the following assumes that. [the GitHub Windows Build Action file](../.github/workflows/windows-build.yml))
1. `git push --set-upstream --tags origin release-4.0.2` 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 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 GitHub. You'll want to reference `stable` or `beta` in the next step, *not
the release-4.0.2 branch, as it's temporary.* 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 1. Use the new tag so as to reference the correct commit, along with the
appropriate `stable` or `beta` branch as the 'Target'. 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. 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). 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 `[ ] 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 Once the release is created, then **only if making a `stable` release**
`edmarketconnector.xml` actually matches where github has placed the `EDMarketConnector_win_<version>.msi` update `edmarketconnector.xml` **in the `releases` branch only** to add this
file.** If, for instance, you fail to *update* this URL then upon running the changelog text to the correct section(s):
'new' installer it will silently fail, because you made people try to install 1. `git checkout releases`
the old version over the old version. 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` grip --export ChangeLog.md
file so no need to redo the build. As this file is only important in the 4. Open `edmarketconnector.xml` in your editor.
`releases` branch you also don't need to redo the GitHub release, i.e. 5. If there's still a Mac OS section croll down past it to the Windows
the release tag doesn't need updating to point to this new commit. 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`.** If, for instance, you fail to *update* this URL then upon running the 'new'
This is the final step that fully publishes the release for running installer it will silently fail, because you made people try to install
EDMC instances to pick up on 'Check for Updates'. The WinSparkle check for the old version over the old version.
updates specifically targets 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` 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
as per `config.py` `update_feed`. updates specifically targets:
1. `git checkout releases`
1. `git merge release-4.0.2` `https://raw.githubusercontent.com/EDCD/EDMarketConnector/releases/edmarketconnector.xml`
1. `git push origin`
as per `config.py` `update_feed`.
(Or merge on GitHub).
NB: It can take some time for GitHub to show the changed
NB: It can take some time for GitHub to show the changed edmarketconnector.xml contents to all users.
edmarketconnector.xml contents to all users.
**You should now update [Known Issues](https://github.com/EDCD/EDMarketConnector/issues/618) **You should now update [Known Issues](https://github.com/EDCD/EDMarketConnector/issues/618)
to reflect anything now fixed in latest release.** 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: If you are making a pre-release then:
1. **DO NOT** Edit edmarketconnector.xml at all. No, not even if you think you 1. **DO NOT** Edit `edmarketconnector.xml` at all. No, not even if you
won't accidentally merge it into `releases`. Just don't change it at all. think you won't accidentally merge it into `releases`. Just don't change it
1. **DO NOT** merge into `releases`. at all.
1. **DO NOT** merge into `stable`. 3. **DO NOT** merge into `releases`.
1. *Do* merge the code into `beta` after you have made a 'pre-release' on 4. **DO NOT** merge into `stable`.
5. *Do* merge the code into `beta` after you have made a 'pre-release' on
GitHub. GitHub.
# Changing Python version # Changing Python version