Revise release instructions #1384
Conversation
Push "Package X.Y.Z" and "Back to -dev" commits separately to ensure Windows build artifacts are created for the tag. Add instructions for creating a maintenance branch after releasing a new minor version.
| The command examples below assume that the canonical "mongodb" repository has | ||
| the remote name "mongodb". You may need to adjust these commands if you've given | ||
| the remote another name (e.g. "upstream"). The "origin" remote name was not used | ||
| as it likely refers to your personal fork. |
There was a problem hiding this comment.
I imagine most development environments are clones of a personal fork, so it's unlikely that "origin" (the default) would be correct. In any event, specifying a remote name in the examples adds clarity.
|
|
||
| It helps to keep your own fork in sync with the "mongodb" repository (i.e. any | ||
| branches and tags on the main repository should also exist in your fork). This | ||
| is left as an exercise to the reader. |
There was a problem hiding this comment.
@alcaeus: I dunno if I've shared this with you, but this is what I use locally:
#!/bin/sh
current=$(git rev-parse --abbrev-ref HEAD)
git fetch mongodb
git fetch origin
for branch in master v1.14 v1.15; do
git checkout $branch && git pull mongodb $branch && git push origin $branch
done
git checkout $currentDunno if you think it's worth documenting elsewhere.
| ``` | ||
|
|
||
| ### Tag release | ||
| > **Note:** Pushing this commit independently from the subsequent "Back to -dev" | ||
| > commit will ensure that Windows build artifacts are created for the release. |
There was a problem hiding this comment.
GitHub Actions are smart enough to not build individual commits if multiple are pushed at once. The original example we had where "Package X.Y.Z" and "Back to -dev" were pushed simultaneously would have meant we never generate build artifacts for the actual tag.
This is clunky and definitely something we could improve down the line if we stop depending on build artifacts from a previous CI run and instead build DLLs on-demand for releases. We could also avoid debug builds and PDB file generation for typical CI runs (I imagine that's a bit slower than without).
There was a problem hiding this comment.
There is the option of pushing them at the same time, then pushing the tag separately and ensuring the tag is built. The workflow syntax allows you to specify tag filters to build on a push: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-branches-and-tags.
If we're updating the process down the line, we could change the process to build tags and create a draft release for them, attaching build artifacts in the process. We could then revise the release notes separately. For now I don't think we need to change this, as I'm sure we'll be working on automating releases (including PECL packages) in the near future.
There was a problem hiding this comment.
Noted. I didn't consider that since we currently only have branch filters in place.
If we revisit release automation down the line I'd definitely suggest writing up a design doc first so we can plan out exactly what we want to implement.
There was a problem hiding this comment.
I agree, that change exceeds the scope of getting this to work. I suggest putting release automation on our quarterly plan and designing this ahead of time 👍
CONTRIBUTING.md
Outdated
| ``` | ||
|
|
||
| The `--strategy=ours` option ensures that all changes from the merged commits | ||
| will be ignored. | ||
| will be ignored. This is OK because previously ensured that the `master` branch | ||
| was up-to-date with all code changes in this maintenance branch before tagging. |
There was a problem hiding this comment.
Thought it'd be helpful to remind readers why this is OK. Technically, we're just ignoring the phongo_version.h changes here.
| -#define PHP_MONGODB_VERSION_DESC 1,1,8,0 | ||
| +#define PHP_MONGODB_VERSION "1.1.8" | ||
| +#define PHP_MONGODB_STABILITY "stable" | ||
| +#define PHP_MONGODB_VERSION_DESC 1,1,8,1 |
There was a problem hiding this comment.
It may be worth mentioning that for going from x.y.z-dev to x.y.z the last digit in this number needs to be increased by 1, not reset to 0. I've been confused by this before, especially during my first releases.
There was a problem hiding this comment.
Isn't that stated in the preceding paragraph?
This should entail removing the version's "-dev" suffix, changing the stability to "stable", and increasing the last digit for
PHP_MONGO_VERSION_DESC:
There was a problem hiding this comment.
I may need new glasses. Thanks for pointing this out!
| ``` | ||
|
|
||
| ### Tag release | ||
| > **Note:** Pushing this commit independently from the subsequent "Back to -dev" | ||
| > commit will ensure that Windows build artifacts are created for the release. |
There was a problem hiding this comment.
There is the option of pushing them at the same time, then pushing the tag separately and ensuring the tag is built. The workflow syntax allows you to specify tag filters to build on a push: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-branches-and-tags.
If we're updating the process down the line, we could change the process to build tags and create a draft release for them, attaching build artifacts in the process. We could then revise the release notes separately. For now I don't think we need to change this, as I'm sure we'll be working on automating releases (including PECL packages) in the near future.
Co-authored-by: Andreas Braun <[email protected]>
Push "Package X.Y.Z" and "Back to -dev" commits separately to ensure Windows build artifacts are created for the tag.
Add instructions for creating a maintenance branch after releasing a new minor version.