From e8143e058b558bbc940cd2d27ac0104444897b3b Mon Sep 17 00:00:00 2001 From: Conda Bot <18747875+conda-bot@users.noreply.github.com> Date: Thu, 8 Aug 2024 21:13:18 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20updated=20file(s)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/PULL_REQUEST_TEMPLATE.md | 15 + .../pull_request_template_details.md | 15 + RELEASE.md | 437 ++++++++++++++++++ rever.xsh | 57 +-- 4 files changed, 483 insertions(+), 41 deletions(-) create mode 100644 .github/template-files/templates/pull_request_template_details.md create mode 100644 RELEASE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 33f6356f2..b31b136c2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,6 +8,21 @@ - any noteworthy (or hacky) choices to be aware of, - or what the problem resolved here looked like. --> +### Checklist - did you ... + + + +- [ ] Add a file to the `news` directory ([using the template](https://github.com/conda/constructor/blob/main/news/TEMPLATE)) for the next release's release notes? + +- [ ] Add / update necessary tests? +- [ ] Add / update outdated documentation? + +- [ ] Add a file to the `news` directory ([using the template](https://github.com/conda/constructor/blob/main/news/TEMPLATE)) for the next release's release notes? + +- [ ] Add / update necessary tests? +- [ ] Add / update outdated documentation? diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..e142df15b --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,437 @@ + + +[epic template]: https://github.com/conda/constructor/issues/new?assignees=&labels=epic&template=epic.yml +[compare]: https://github.com/conda/constructor/compare +[new release]: https://github.com/conda/constructor/releases/new +[infrastructure]: https://github.com/conda/infrastructure +[rever docs]: https://regro.github.io/rever-docs +[release docs]: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes +[merge conflicts]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts +[Anaconda Recipes]: https://github.com/AnacondaRecipes/constructor-feedstock +[conda-forge]: https://github.com/conda-forge/constructor-feedstock + +# Release Process + +> [!NOTE] +> Throughout this document are references to the version number as `MAJOR.MINOR.[$patch_number]`, this should be replaced with the correct version number. Do **not** prefix the version with a lowercase `v`. + +## 1. Open the release issue and cut a release branch. (do this ~1 week prior to release) + +> [!NOTE] +> The new release branch should adhere to the naming convention of `MAJOR.MINOR.x` (make sure to put the `.x` at the end!). In the case of patch/hotfix releases, however, do NOT cut a new release branch; instead, use the previously-cut release branch with the appropriate `MAJOR.MINOR.x` version numbers. + +Use the issue template below to create the release issue. After creating the release issue, pin it for easy access. + +
+

Release Template

 + +```markdown +### Summary + +Placeholder for `constructor MAJOR.MINOR.x` release. + +| Pilot | | +|---|---| +| Co-pilot | | + +### Tasks + +[milestone]: https://github.com/conda/constructor/milestone/ +[process]: https://github.com/conda/constructor/blob/main/RELEASE.md +[releases]: https://github.com/conda/constructor/releases +[main]: https://github.com/AnacondaRecipes/constructor-feedstock +[conda-forge]: https://github.com/conda-forge/constructor-feedstock +[ReadTheDocs]: https://readthedocs.com/projects/continuumio-constructor/ + +
+

The week before release week

 + +- [ ] Create release branch (named `MAJOR.MINOR.x`) +- [ ] Ensure release candidates are being successfully built (see `conda-canary/label/rc-constructor-MAJOR.MINOR.x`) +- [ ] [Complete outstanding PRs][milestone] +- [ ] Test release candidates + + +
+ +
+

Release week

 + +- [ ] Create release PR (see [release process][process]) +- [ ] [Publish release][releases] +- [ ] Merge `MAJOR.MINOR.x` back into `main` +- [ ] Activate the `MAJOR.MINOR.x` branch on [ReadTheDocs][ReadTheDocs] +- [ ] Feedstocks + - [ ] Bump version & update dependencies/tests in [Anaconda, Inc.'s feedstock][main] + - [ ] Bump version & update dependencies/tests in [conda-forge feedstock][conda-forge] + +- [ ] Hand off to the Anaconda packaging team +- [ ] Announce release + - Blog Post (optional) + - [ ] conda.org (link to pull request) + - Long form + - [ ] Create release [announcement draft](https://github.com/conda/communications) + - [ ] [Discourse](https://conda.discourse.group/) + - [ ] [Matrix (conda/conda)](https://matrix.to/#/#conda_conda:gitter.im) (this auto posts from Discourse) + - Summary + - [ ] [Twitter](https://twitter.com/condaproject) + +
+``` +
+ +If a patch release is necessary, reopen the original release issue and append the following template to the release issue summary. + +
+

Patch Release Template

 + +```markdown +
+

Patch MAJOR.MINOR.[$patch_number]

 + +- [ ] +- [ ] Create release PR (see [release process][process]) +- [ ] [Publish release][releases] +- [ ] Merge `MAJOR.MINOR.x` back into `main` +- [ ] Feedstocks + - [ ] Bump version & update dependencies/tests in [Anaconda, Inc.'s feedstock][main] + - [ ] Bump version & update dependencies/tests in [conda-forge feedstock][conda-forge] +- [ ] Hand off to the Anaconda packaging team + +
+``` + +
+ +> [!NOTE] +> The [epic template][epic template] is perfect for this; remember to remove the **`epic`** label. + +## 2. Alert various parties of the upcoming release. (do this ~1 week prior to release) + +Let various interested parties know about the upcoming release; at minimum, conda-forge maintainers should be informed. For major features, a blog post describing the new features should be prepared and posted once the release is completed (see the announcements section of the release issue). + +## 3. Manually test canary build(s). + +### Canary Builds for Manual Testing + +Once the release PRs are filed, successful canary builds will be available on `https://anaconda.org/conda-canary/conda/files?channel=rc-constructor-MAJOR.MINOR.x` for manual testing. + +> [!NOTE] +> You do not need to apply the `build::review` label for release PRs; every commit to the release branch builds and uploads canary builds to the respective `rc-` label. + +## 4. Ensure `rever.xsh` and `news/TEMPLATE` are up to date. + +These are synced from [`conda/infrastructure`][infrastructure]. + +
+

5. Run rever. (ideally done on the Monday of release week)

 + +Currently, there are only 2 activities we use rever for, (1) aggregating the authors and (2) updating the changelog. Aggregating the authors can be an error-prone process and also suffers from builtin race conditions (_i.e._, to generate an updated `.authors.yml` we need an updated `.mailmap` but to have an updated `.mailmap` we need an updated `.authors.yml`). This is why the following steps are very heavy-handed (and potentially repetitive) in running rever commands, undoing commits, squashing/reordering commits, etc. + +1. Install [`rever`][rever docs] and activate the environment: + + ```bash + $ conda create -n rever conda-forge::rever + $ conda activate rever + (rever) $ + ``` + +2. Clone and `cd` into the repository if you haven't done so already: + + ```bash + (rever) $ git clone git@github.com:/constructor.git + (rever) $ cd conda + ``` + +2. Fetch the latest changes from the remote and checkout the release branch created a week ago: + + ```bash + (rever) $ git fetch upstream + (rever) $ git checkout MAJOR.MINOR.x + ``` + +2. Create a versioned branch, this is where rever will make its changes: + + ```bash + (rever) $ git checkout -b changelog-MAJOR.MINOR.[$patch_number] + ``` + +2. Run `rever --activities authors `: + + > **Note:** + > Include `--force` when re-running any rever commands for the same ``, otherwise, rever will skip the activity and no changes will be made (i.e., rever remembers if an activity has been run for a given version). + + ```bash + (rever) $ rever --activities authors --force + ``` + + - If rever finds that any of the authors are not correctly represented in `.authors.yml` it will produce an error. If the author that the error pertains to is: + - **a new contributor**: the snippet suggested by rever should be added to the `.authors.yml` file. + - **an existing contributor**, a result of using a new name/email combo: find the existing author in `.authors.yml` and add the new name/email combo to that author's `aliases` and `alterative_emails`. + + - Once you have successfully run `rever --activities authors` with no errors, review the commit made by rever. This commit will contain updates to one or more of the author files (`.authors.yml`, `.mailmap`, and `AUTHORS.md`). Due to the race condition between `.authors.yml` and `.mailmap`, we want to extract changes made to any of the following keys in `.authors.yml` and commit them separately from the other changes in the rever commit: + - `name` + - `email` + - `github` + - `aliases` + - `alternate_emails` + + Other keys (e.g., `num_commits` and `first_commit`) do not need to be included in this separate commit as they will be overwritten by rever. + + - Here's a sample run where we undo the commit made by rever in order to commit the changes to `.authors.yml` separately: + + ```bash + (rever) $ rever --activities authors --force MAJOR.MINOR.[$patch_number] + + # changes were made to .authors.yml as per the prior bullet + (rever) $ git diff --name-only HEAD HEAD~1 + .authors.yml + .mailmap + AUTHORS.md + + # undo commit + (rever) $ git reset --soft HEAD~1 + + # undo changes made to everything except .authors.yml + (rever) $ git restore --staged --worktree .mailmap AUTHORS.md + ``` + + - Commit these changes to `.authors.yml`: + + ```bash + (rever) $ git add . + (rever) $ git commit -m "Update .authors.yml" + ``` + + - Rerun `rever --activities authors --force ` and finally check that your `.mailmap` is correct by running: + + ```bash + git shortlog -se + ``` + + Compare this list with `AUTHORS.md`. If they have any discrepancies, additional modifications to `.authors.yml` is needed, so repeat the above steps as needed. + + - Once you are pleased with how the author's file looks, we want to undo the rever commit and commit the `.mailmap` changes separately: + + ```bash + # undo commit (but preserve changes) + (rever) $ git reset --soft HEAD~1 + + # undo changes made to everything except .mailmap + (rever) $ git restore --staged --worktree .authors.yml AUTHORS.md + ``` + + - Commit these changes to `.mailmap`: + + ```bash + (rever) $ git add . + (rever) $ git commit -m "Update .mailmap" + ``` + + - Continue repeating the above processes until the `.authors.yml` and `.mailmap` are corrected to your liking. After completing this, you will have at most two commits on your release branch: + + ```bash + (rever) $ git cherry -v + + 86957814cf235879498ed7806029b8ff5f400034 Update .authors.yml + + 3ec7491f2f58494a62f1491987d66f499f8113ad Update .mailmap + ``` + + +4. Review news snippets (ensure they are all using the correct Markdown format, **not** reStructuredText) and add additional snippets for undocumented PRs/changes as necessary. + + > **Note:** + > We've found it useful to name news snippets with the following format: `-`. + > + > We've also found that we like to include the PR #s inline with the text itself, e.g.: + > + > ```markdown + > ## Enhancements + > + > * Add `win-arm64` as a known platform (subdir). (#11778) + > ``` + + - You can utilize [GitHub's compare view][compare] to review what changes are to be included in this release. Make sure you compare the current release branch against the previous one (e.g., `24.5.x` would be compared against `24.3.x`) + + - Add a new news snippet for any PRs of importance that are missing. + + - Commit these changes to news snippets: + + ```bash + (rever) $ git add . + (rever) $ git commit -m "Update news" + ``` + + - After completing this, you will have at most three commits on your release branch: + + ```bash + (rever) $ git cherry -v + + 86957814cf235879498ed7806029b8ff5f400034 Update .authors.yml + + 3ec7491f2f58494a62f1491987d66f499f8113ad Update .mailmap + + 432a9e1b41a3dec8f95a7556632f9a93fdf029fd Update news + ``` + +5. Run `rever --activities changelog`: + + > **Note:** + > This has previously been a notoriously fickle step (likely due to incorrect regex patterns in the `rever.xsh` config file and missing `github` keys in `.authors.yml`) so beware of potential hiccups. If this fails, it's highly likely to be an innocent issue. + + ```bash + (rever) $ rever --activities changelog --force + ``` + + - Any necessary modifications to `.authors.yml`, `.mailmap`, or the news snippets themselves should be amended to the previous commits. + + - Once you have successfully run `rever --activities changelog` with no errors simply revert the last commit (see the next step for why): + + ```bash + # undo commit (and discard changes) + (rever) $ git reset --hard HEAD~1 + ``` + + - After completing this, you will have at most three commits on your release branch: + + ```bash + (rever) $ git cherry -v + + 86957814cf235879498ed7806029b8ff5f400034 Update .authors.yml + + 3ec7491f2f58494a62f1491987d66f499f8113ad Update .mailmap + + 432a9e1b41a3dec8f95a7556632f9a93fdf029fd Update news + ``` + +6. Now that we have successfully run the activities separately, we wish to run both together. This will ensure that the contributor list, a side-effect of the authors activity, is included in the changelog activity. + + ```bash + (rever) $ rever --force + ``` + + - After completing this, you will have at most five commits on your release branch: + + ```bash + (rever) $ git cherry -v + + 86957814cf235879498ed7806029b8ff5f400034 Update .authors.yml + + 3ec7491f2f58494a62f1491987d66f499f8113ad Update .mailmap + + 432a9e1b41a3dec8f95a7556632f9a93fdf029fd Update news + + a5c0db938893d2c12cab12a1f7eb3e646ed80373 Update authorship for MAJOR.MINOR.[$patch_number] + + 5e95169d0df4bcdc2da9a6ba4a2561d90e49f75d Update CHANGELOG for MAJOR.MINOR.[$patch_number] + ``` + +7. Since rever does not include stats on first-time contributors, we will need to add this manually. + + - Use [GitHub's auto-generated release notes][new release] to get a list of all new contributors (and their first PR) and manually merge this list with the contributor list in `CHANGELOG.md`. See [GitHub docs][release docs] for how to auto-generate the release notes. + + - Commit these final changes: + + ```bash + (rever) $ git add . + (rever) $ git commit -m "Add first-time contributions" + ``` + + - After completing this, you will have at most six commits on your release branch: + + ```bash + (rever) $ git cherry -v + + 86957814cf235879498ed7806029b8ff5f400034 Update .authors.yml + + 3ec7491f2f58494a62f1491987d66f499f8113ad Update .mailmap + + 432a9e1b41a3dec8f95a7556632f9a93fdf029fd Update news + + a5c0db938893d2c12cab12a1f7eb3e646ed80373 Update authorship for MAJOR.MINOR.[$patch_number] + + 5e95169d0df4bcdc2da9a6ba4a2561d90e49f75d Update CHANGELOG for MAJOR.MINOR.[$patch_number] + + 93fdf029fd4cf235872c12cab12a1f7e8f95a755 Add first-time contributions + ``` + +8. Push this versioned branch. + + ```bash + (rever) $ git push -u upstream changelog-MAJOR.MINOR.[$patch_number] + ``` + +9. Open the Release PR targing the `MAJOR.MINOR.x` branch. + +
+ GitHub PR Template + + ```markdown + ## Description + + ✂️ snip snip ✂️ the making of a new release. + + Xref # + ``` + +
+ +10. Update release issue to include a link to the release PR. + +11. [Create][new release] the release and **SAVE AS A DRAFT** with the following values: + + > **Note:** + > Only publish the release after the release PR is merged, until then always **save as draft**. + + | Field | Value | + |---|---| + | Choose a tag | `MAJOR.MINOR.[$patch_number]` | + | Target | `MAJOR.MINOR.x` | + | Body | copy/paste blurb from `CHANGELOG.md` | + +
+ +## 6. Wait for review and approval of release PR. + +## 7. Merge release PR and publish release. + +To publish the release, go to the project's release page (e.g., https://github.com/conda/conda/releases) and add the release notes from `CHANGELOG.md` to the draft release you created earlier. Then publish the release. + +> [!NOTE] +> Release notes can be drafted and saved ahead of time. + +## 8. Merge/cherry pick the release branch over to the `main` branch. + +
+Internal process + +1. From the main "< > Code" page of the repository, select the drop down menu next to the `main` branch button and then select "View all branches" at the very bottom. + +2. Find the applicable `MAJOR.MINOR.x` branch and click the "New pull request" button. + +3. "Base" should point to `main` while "Compare" should point to `MAJOR.MINOR.x`. + +4. Ensure that all of the commits being pulled in look accurate, then select "Create pull request". + +> [!NOTE] +> Make sure NOT to push the "Update Branch" button. If there are [merge conflicts][merge conflicts], create a temporary "connector branch" dedicated to fixing merge conflicts separately from the `MAJOR.MINOR.x` and `main` branches. + +5. Review and merge the pull request the same as any code change pull request. + +> [!NOTE] +> The commits from the release branch need to be retained in order to be able to compare individual commits; in other words, a "merge commit" is required when merging the resulting pull request vs. a "squash merge". Protected branches will require permissions to be temporarily relaxed in order to enable this action. + +
+ +## 9. Open PRs to bump [Anaconda Recipes][Anaconda Recipes] and [conda-forge][conda-forge] feedstocks to use `MAJOR.MINOR.[$patch_number]`. + +> [!NOTE] +> Conda-forge's PRs will be auto-created via the `regro-cf-autotick-bot`. Follow the instructions below if any changes need to be made to the recipe that were not automatically added (these instructions are only necessary for anyone who is _not_ a conda-forge feedstock maintainer, since maintainers can push changes directly to the autotick branch): +> - Create a new branch based off of autotick's branch (autotick's branches usually use the `regro-cf-autotick-bot:XX.YY.[$patch_number]_[short hash]` syntax) +> - Add any changes via commits to that new branch +> - Open a new PR and push it against the `main` branch +> +> Make sure to include a comment on the original `autotick-bot` PR that a new pull request has been created, in order to avoid duplicating work! `regro-cf-autotick-bot` will close the auto-created PR once the new PR is merged. +> +> For more information about this process, please read the ["Pushing to regro-cf-autotick-bot branch" section of the conda-forge documentation](https://conda-forge.org/docs/maintainer/updating_pkgs.html#pushing-to-regro-cf-autotick-bot-branch). + + +## 10. Hand off to Anaconda's packaging team. + +> [!NOTE] +> This step should NOT be done past Thursday morning EST; please start the process on a Monday, Tuesday, or Wednesday instead in order to avoid any potential debugging sessions over evenings or weekends. + +
+Internal process + +1. Open packaging request in #package_requests Slack channel, include links to the Release PR and feedstock PRs. + +2. Message packaging team/PM to let them know that a release has occurred and that you are the release manager. + +
+ +## 11. Continue championing and shepherding. + +Remember to make all relevant announcements and continue to update the release issue with the latest details as tasks are completed. diff --git a/rever.xsh b/rever.xsh index 5d29e9324..c25154fed 100644 --- a/rever.xsh +++ b/rever.xsh @@ -1,61 +1,36 @@ -from rever.activities.authors import Authors as ReverAuthors, update_metadata, eval_version, SORTINGS +# edit this in https://github.com/conda/infrastructure -class ConstructorAuthors(ReverAuthors): - def _update_authors(self, filename, template, format, metadata, sortby, include_orgs): - """helper function for updating / writing authors file""" - md = update_metadata(metadata) - template = eval_version(template) - sorting_key, sorting_text = SORTINGS[sortby] - md = sorted(md, key=sorting_key) - if not include_orgs: - md = [x for x in md if not x.get("is_org", False)] - aformated = "".join([format.format(**x) for x in md]) - s = template.format(sorting_text=sorting_text, authors=aformated) - s = s.rstrip() + "\n" - # fixing an issue that is related to Unicode surrogates - # (in one of the committer's names) - with open(filename, 'w') as f: - f.write(s.encode("utf-8", "surrogateescape").decode("utf-8", "replace")) - return md +$ACTIVITIES = ["authors", "changelog"] - -$DAG['authors'] = ConstructorAuthors() # register the activity - - -$ACTIVITIES = [ - "authors", - "changelog", - # "tag", - # "push_tag", - # "ghrelease", - # "conda_forge" - ] - -# # Basic settings -# -$PROJECT = $GITHUB_REPO = "constructor" +$PROJECT = $GITHUB_REPO = $(basename $(git remote get-url origin)).split('.')[0].strip() $GITHUB_ORG = "conda" + +# Authors settings $AUTHORS_FILENAME = "AUTHORS.md" $AUTHORS_SORTBY = "alpha" -# # Changelog settings -# $CHANGELOG_FILENAME = "CHANGELOG.md" $CHANGELOG_PATTERN = r"\[//\]: # \(current developments\)" $CHANGELOG_HEADER = """[//]: # (current developments) -## $RELEASE_DATE $VERSION: +## $VERSION ($RELEASE_DATE) + """ -$CHANGELOG_CATEGORIES = ( +$CHANGELOG_CATEGORIES = [ "Enhancements", "Bug fixes", "Deprecations", "Docs", "Other", -) -$CHANGELOG_CATEGORY_TITLE_FORMAT = '### {category}\n\n' - +] +$CHANGELOG_CATEGORY_TITLE_FORMAT = "### {category}\n\n" $CHANGELOG_AUTHORS_TITLE = "Contributors" $CHANGELOG_AUTHORS_FORMAT = "* @{github}\n" + +try: + # allow repository to customize synchronized-from-infa rever config + from rever_overrides import * +except ImportError: + pass