From a4768d08e172e009efb7ccafb8dc37a90753df7f Mon Sep 17 00:00:00 2001 From: Rafael M Mudafort Date: Wed, 8 Nov 2023 17:54:40 -0600 Subject: [PATCH] Add documentation for the release process (#727) --- docs/dev_guide.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/docs/dev_guide.md b/docs/dev_guide.md index ac1b32da2..fcb3feb11 100644 --- a/docs/dev_guide.md +++ b/docs/dev_guide.md @@ -224,6 +224,70 @@ jupyter-book build docs/ open docs/_build/html/index.html ``` +## Release guide + +Follow the process outlined here to "release" FLORIS. +After completing these steps, a few additional automated processes +are launched to deploy FLORIS to PyPI and conda-forge. +Be sure to complete each step in the sequence as described. + +1. Merge the `develop` branch into `main` with a pull request. + Create a pull request titled `FLORIS vN.M` with version number filled in + as appropriate. + The body of the pull request should a brief summary of the changes + as well as a listing of the major changes and their associated pull requests. + Since creating the pull request does not mean it is merged, it is + reasonable to create the pull request, and edit the body of the pull + request later. + The pull request template has a checklist at the bottom that should be + uncommented for this PR. + +2. Update the version number and commit to the `develop`` branch + with a commit message such as "Update version to vN.M". + The version number must be updated in the following two files: + - [floris/README.md](https://github.com/NREL/floris/blob/main/README.md) + - [floris/floris/version.py](https://github.com/NREL/floris/blob/main/floris/version.py) + Note that a `.0` version number is left off meaning that valid versions + are `v3`, `v3.1`, `v3.1.1`, etc. + +3. Verify that the documentation is building correctly. + The docs build for every commit to `develop`, so there should be no + surprises in this regard prior to a release. However, it's a good + opportunity to ensure that the documentation is up to date and there + are no obvious issues. + Check this by opening the documentation website at https://nrel.github.io/floris/intro.html + and scrolling through the pages. + Also, verify that the automated build process has successfully completed + for the commits to `develop` in [GitHub Actions](https://github.com/NREL/floris/actions/workflows/deploy-pages.yaml). + +4. The changes since the prior commit can be gotten from GitHub by going through the + process to create a release, but stopping short of actually publishing it. + In this form, GitHub provides the option to autogenerate release notes. + Be sure to choose the correct starting tag, and then hit "Generate release notes". + Then, copy the generated text into the pull request body, and format it + as appropriate. A good reference is typically the previous release. + +5. Merge the pull request into `main`. Select "Create a merge commit" from the merge + dropdown, and hit "Merge pull request". + +6. Create a [new release](https://github.com/NREL/floris/releases/new) on GitHub + with the title "vN.M". Choose to create a new tag on publish with the same + name. Also, autogenerate the release notes again. If you autogenerated the release + notes in step 4, make sure to start this step from a new browser window. + Be sure that the "Set as latest release" radio button is enabled. + +7. Double check everything. + +8. Hit "Publish release". + +9. Go to GitHub Actions and watch the [Upload Python Package](https://github.com/NREL/floris/actions/workflows/python-publish.yml) + job complete. Upon success, FLORIS will be uploaded to PyPI for installation with pip. + If it fails, the latest release will not be distributed. + +10. Merge the main branch into develop to align all branches on all remotes. + +11. That's it, well done! + ## Deploying to pip Generally, only NREL developers will have appropriate permissions to deploy