diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7ca7e20..15edc7f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -178,9 +178,9 @@ jobs: - name: "Run Tests" run: "poetry run invoke unittest" changelog: - if: | + if: > contains(fromJson('["develop","ltm-1.6"]'), github.base_ref) && - (github.head_ref != 'main') + (github.head_ref != 'main') && !contains(github.head_ref, 'release') runs-on: "ubuntu-22.04" steps: - name: "Check out repository code" diff --git a/changes/1.changed b/changes/1.changed deleted file mode 100644 index 434058b..0000000 --- a/changes/1.changed +++ /dev/null @@ -1 +0,0 @@ -Cleaned up the baked cookie. diff --git a/changes/10.housekeeping b/changes/10.housekeeping deleted file mode 100644 index f24ee80..0000000 --- a/changes/10.housekeeping +++ /dev/null @@ -1 +0,0 @@ -Fixed NTC link in `README.md`. diff --git a/changes/14.housekeeping b/changes/14.housekeeping deleted file mode 100644 index 972f1cd..0000000 --- a/changes/14.housekeeping +++ /dev/null @@ -1 +0,0 @@ -Fully integrated ruff as a (partial) replacement for the other linters. \ No newline at end of file diff --git a/changes/16.housekeeping b/changes/16.housekeeping deleted file mode 100644 index 059899b..0000000 --- a/changes/16.housekeeping +++ /dev/null @@ -1 +0,0 @@ -More additions on ruff integration. \ No newline at end of file diff --git a/changes/20.fixed b/changes/20.fixed deleted file mode 100644 index a0739af..0000000 --- a/changes/20.fixed +++ /dev/null @@ -1 +0,0 @@ -Removed deprecated default-authentication-plugin setting for mysql containers. diff --git a/changes/6.housekeeping b/changes/6.housekeeping deleted file mode 100644 index 09a4b12..0000000 --- a/changes/6.housekeeping +++ /dev/null @@ -1 +0,0 @@ -Fixed the documentation to explain the app usage. diff --git a/changes/7.housekeeping b/changes/7.housekeeping deleted file mode 100644 index 7c45fe7..0000000 --- a/changes/7.housekeeping +++ /dev/null @@ -1,2 +0,0 @@ -Bumped `networktocode/gh-action-setup-poetry-environment` from `v5` to `v6`. -Bumped `actions/setup-python` from `v4` to `v5`. diff --git a/changes/8.housekeeping b/changes/8.housekeeping deleted file mode 100644 index 653c54a..0000000 --- a/changes/8.housekeeping +++ /dev/null @@ -1 +0,0 @@ -Re-baked from the latest template. diff --git a/changes/9.housekeeping b/changes/9.housekeeping deleted file mode 100644 index 653c54a..0000000 --- a/changes/9.housekeeping +++ /dev/null @@ -1 +0,0 @@ -Re-baked from the latest template. diff --git a/docs/admin/release_notes/version_1.0.md b/docs/admin/release_notes/version_1.0.md index 5f51280..4746a37 100644 --- a/docs/admin/release_notes/version_1.0.md +++ b/docs/admin/release_notes/version_1.0.md @@ -8,20 +8,24 @@ This document describes all new features and changes in the release `1.0`. The f - Achieved in this `x.y` release - Changes to compatibility with Nautobot and/or other apps, libraries etc. -## [v1.0.1] - 2021-09-08 - -### Added +## [v1.0.0 (2024-07-04)](https://github.com/nautobot/nautobot-app-dev-example/releases/tag/v1.0.0) ### Changed -### Fixed - -- [#123](https://github.com/nautobot/nautobot-app-dev-example/issues/123) Fixed Tag filtering not working in job launch form +- [#1](https://github.com/nautobot/nautobot-app-dev-example/issues/1) - Cleaned up the baked cookie. +- [#21](https://github.com/nautobot/nautobot-app-dev-example/issues/21) - Updated steps to create releases. +- [#21](https://github.com/nautobot/nautobot-app-dev-example/issues/21) - Changed CI changelog step to ignore branch names starting with "release". -## [v1.0.0] - 2021-08-03 +### Fixed -### Added +- [#20](https://github.com/nautobot/nautobot-app-dev-example/issues/20) - Removed deprecated default-authentication-plugin setting for mysql containers. -### Changed +### Housekeeping -### Fixed +- [#6](https://github.com/nautobot/nautobot-app-dev-example/issues/6) - Fixed the documentation to explain the app usage. +- [#7](https://github.com/nautobot/nautobot-app-dev-example/issues/7) - Bumped `networktocode/gh-action-setup-poetry-environment` from `v5` to `v6`. +- [#7](https://github.com/nautobot/nautobot-app-dev-example/issues/7) - Bumped `actions/setup-python` from `v4` to `v5`. +- [#8](https://github.com/nautobot/nautobot-app-dev-example/issues/8), [#9](https://github.com/nautobot/nautobot-app-dev-example/issues/9) - Re-baked from the latest template. +- [#10](https://github.com/nautobot/nautobot-app-dev-example/issues/10) - Fixed NTC link in `README.md`. +- [#14](https://github.com/nautobot/nautobot-app-dev-example/issues/14) - Fully integrated ruff as a (partial) replacement for the other linters. +- [#16](https://github.com/nautobot/nautobot-app-dev-example/issues/16) - More additions on ruff integration. diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md index 4e6b405..5efd2ee 100644 --- a/docs/dev/contributing.md +++ b/docs/dev/contributing.md @@ -53,20 +53,4 @@ Nautobot Dev Example App will observe semantic versioning, as of 1.0. This may r Nautobot Dev Example App has currently no intended scheduled release schedule, and will release new features in minor versions. -When a new release, from `develop` to `main`, is created the following should happen. - -- A release PR is created from `develop` with: - - Update the release notes in `docs/admin/release_notes/version_..md` file to reflect the changes. - - Change the version from `..-beta` to `..` in `pyproject.toml`. - - Set the PR to the `main` branch. -- Ensure the tests for the PR pass. -- Merge the PR. -- Create a new tag: - - The tag should be in the form of `v..`. - - The title should be in the form of `v..`. - - The description should be the changes that were added to the `version_..md` document. -- If merged into `main`, then push from `main` to `develop`, in order to retain the merge commit created when the PR was merged -- A post release PR is created with: - - Change the version from `..` to `..-beta` in both `pyproject.toml` and `nautobot.__init__.__version__`. - - Set the PR to the proper branch, `develop`. - - Once tests pass, merge. +The steps taken by maintainers when creating a new release are documented in the [release checklist](./release_checklist.md). diff --git a/docs/dev/release_checklist.md b/docs/dev/release_checklist.md new file mode 100644 index 0000000..e68266a --- /dev/null +++ b/docs/dev/release_checklist.md @@ -0,0 +1,135 @@ +# Release Checklist + +This document is intended for app maintainers and covers the steps to perform when releasing new versions of the app. + +## Minor Version Bumps + +### Update Requirements + +Every minor version release should refresh `poetry.lock`, so that it lists the most recent stable release of each package. To do this: + +0. Run `poetry update --dry-run` to have Poetry automatically tell you what package updates are available and the versions it would upgrade to. This requires an existing environment created from the lock file (i.e. via `poetry install`). +1. Review each requirement's release notes for any breaking or otherwise noteworthy changes. +2. Run `poetry update ` to update the package versions in `poetry.lock` as appropriate. +3. If a required package requires updating to a new release not covered in the version constraints for a package as defined in `pyproject.toml`, (e.g. `Django ~3.1.7` would never install `Django >=4.0.0`), update it manually in `pyproject.toml`. +4. Run `poetry install` to install the refreshed versions of all required packages. +5. Run all tests (`poetry run invoke tests`) and check that the UI and API function as expected. + +### Update Documentation + +Commit any resulting changes from the following sections to the documentation before proceeding with the release. + +!!! tip + Fire up the documentation server in your development environment with `poetry run mkdocs serve`! This allows you to view the documentation site locally (the link is in the output of the command) and automatically rebuilds it as you make changes. + +#### Link to the Release Notes Page + +A new minor version requires the creation of a new release notes page in the documentation (e.g. `docs/admin/release_notes/version_X.Y.md`). Add this new page to the table of contents within `mkdocs.yml`. + +### Verify the Installation and Upgrade Steps + +Follow the [installation instructions](../admin/install.md) to perform a new production installation of the app. If possible, also test the [upgrade process](../admin/upgrade.md) from the previous released version. + +The goal of this step is to walk through the entire install process *as documented* to make sure nothing there needs to be changed or updated, to catch any errors or omissions in the documentation, and to ensure that it is current with each release. + +--- + +## All Releases + +### Verify CI Build Status + +Ensure that continuous integration testing on the `develop` branch is completing successfully. + +### Bump the Version + +Update the package version using `poetry version` if necessary. This command shows the current version of the project or bumps the version of the project and writes the new version back to `pyproject.toml` if a valid bump rule is provided. + +The new version must be a valid semver string or a valid bump rule: `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`. Always try to use a bump rule when you can. + +Display the current version with no arguments: + +```no-highlight +> poetry version +nautobot-dev-example 1.0.0-beta.2 +``` + +Bump pre-release versions using `prerelease`: + +```no-highlight +> poetry version prerelease +Bumping version from 1.0.0-beta.2 to 1.0.0-beta.3 +``` + +For major versions, use `major`: + +```no-highlight +> poetry version major +Bumping version from 1.0.0-beta.2 to 1.0.0 +``` + +For patch versions, use `minor`: + +```no-highlight +> poetry version minor +Bumping version from 1.0.0 to 1.1.0 +``` + +And lastly, for patch versions, you guessed it, use `patch`: + +```no-highlight +> poetry version patch +Bumping version from 1.1.0 to 1.1.1 +``` + +Please see the [official Poetry documentation on `version`](https://python-poetry.org/docs/cli/#version) for more information. + +### Update the Changelog + +!!! important + The changelog must adhere to the [Keep a Changelog](https://keepachangelog.com/) style guide. + +This example uses 1.4.2, but change the version number to match the version you bumped to in the previous step. First, create a release branch off of `develop` (`git switch -c release-1.4.2 develop`). + +Generate release notes with `invoke generate-release-notes --version 1.4.2` and answer `yes` to the prompt `Is it okay if I remove those files? [Y/n]:`. This will update the release notes in `docs/admin/release_notes/version_1.4.md`, stage that file in git, and `git rm` all the fragments that have now been incorporated into the release notes. + +Check the git diff to verify the changes are correct (`git diff --cached`). + +Commit and push the staged changes. + +### Submit Release Pull Request + +Submit a pull request to merge your release branch into `develop`. Once merged, submit another pull request titled `**"Release vX.Y.Z"**` to merge the `develop` branch into `main`. Copy the documented release notes into the pull request's body. + +Once CI has completed on the PR, merge it. + +!!! important + Do not squash merge this branch into `main`. Make sure to select `Create a merge commit` when merging in GitHub. + +### Create a New Release in GitHub + +Draft a [new release](https://github.com/nautobot/nautobot-app-dev-example/releases/new) with the following parameters. + +* **Tag:** Current version (e.g. `v1.4.2`) +* **Target:** `main` +* **Title:** Version and date (e.g. `v1.4.2 - 2024-04-02`) + +Click "Generate Release Notes" and keep the `Full Changelog` section (delete everything else). Copy the description from the pull request to the release. + +### Create a PR from `main` back to `develop` + +Create a new branch from `main` called `release-1.4.2-to-develop` and use `poetry version prepatch` to bump the development version to the next release. + +For example, if you just released `v1.4.2`: + +```no-highlight +> git switch -c release-1.4.2-to-develop main +Switched to a new branch 'release-1.4.2-to-develop' + +> poetry version prepatch +Bumping version from 1.4.2 to 1.4.3a1 +``` + +Open a new PR from `release-1.4.2-to-develop` against `develop`, wait for CI to pass, and merge it. + +!!! important + Do not squash merge this branch into `develop`. Make sure to select `Create a merge commit` when merging in GitHub. diff --git a/mkdocs.yml b/mkdocs.yml index f68ccf9..529d797 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,7 @@ nav: - Extending the App: "dev/extending.md" - Contributing to the App: "dev/contributing.md" - Development Environment: "dev/dev_environment.md" + - Release Checklist: "dev/release_checklist.md" - Architecture Decision Records: "dev/arch_decision.md" - Code Reference: - "dev/code_reference/index.md" diff --git a/pyproject.toml b/pyproject.toml index 21db58b..b2dabc3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "nautobot-dev-example" -version = "0.1.0" +version = "1.0.0" description = "Nautobot App to demonstrate how to create a Nautobot App." authors = ["Network to Code, LLC "] license = "Apache-2.0"