The intention of this page is to document the acquisitions-specific release procedures, best practices, lessons learned, and other related information.
Milestone Dates and Terminology
Description of feature freeze, code freeze, etc.
- Release Cycle
- A release cycle consists of two consecutive sprints, typically coinciding with the community-wide "sprint demos"
- Feature Freeze
- Any user stories started after this date will be applied to the next release, not the current one.
- Usually takes place on the 3rd Friday of the release cycle.
- Code Freeze
- Any changes made after this date will be applied to the next release, not the current one.
- Release branches will be made as soon after code freeze as possible.
- Usually takes place on the last Wednesday of the release cycle.
- Sprint Demo
- The community-wide sprint demonstration.
- Usually takes place on the first Tuesday following a release cycle.
Additional Details TBD.
High level description of the steps required to perform a release.
Acquisitions-specific Steps - Refers to steps in the Community Release Guide linked above, but adds additional steps/sequencing for improved coordination and communication.
ui-modules: check that latest translations are in place (especially if you've changed existing values in en.json).
- Before you do anything, communicate with the team. Let them know during daily standup that you're planning on starting a release.
- Determine the release and next versions - See https://dev.folio.org/guidelines/contributing/#version-numbers - Discuss with the team if unsure about either.
- Create a release branch (See Best Practices)
- Update the
NEWS/CHANGELOG.mdfile (See Best Practices)
- Make use of JIRA and add any stories that have been completed in this version but are missing from the NEWS/Changelog file.
- Bump interface versions that have changed (minor number if backwards compatible, major number if breaking changes)
- N.B. Make sure all required interface versions have been released. If not, raise the issue with the PO/Tech Lead.
- Commit and push your changes
- Create A PR (See Best Practices) and request approval. If there are mistakes this is the time to identify them, BEFORE creating a tag.
- Once you have at least 2 approvals:
- Backend Only: Run the maven command to create the tag and prepare for the next release, then push the pom file changes AND tags
- UI Only: Create a tag.
- If the PR checks pass, DO NOT merge your PR yet... Goto Jenkins, find your module, find your tag, and build it.
- If the tag build succeeded, Goto your github repo, merge the release's PR, click on releases, and draft a new release. Copy/Paste in the section of your NEWS into the release notes and save/publish.
- Announce your release in the #acquisitions-dev and #releases channels with a link to the release
- Coordinate with the rest of the team before merging any PRs into master.
- If there were interface/dependency changes there's a good chance multiple PRs will need to be merged together to prevent breaking the testing environment.
- The team may decide to hold off on merging any PRs until after the sprint demo. You don't want to be the reason why someone's demo isn't working.
- Create a PR updating platform-complete files as per https://dev.folio.org/guidelines/release-procedures/#platform-edit-steps. Don't forget install-extras.json for edge APIs!
- Move your JIRA to "In Review" and assign to the Scrum Master.
- The Scrum Master can safely close the story and update the JIRA releases/versions
- If the module has API tests:
- Create a branch of folio-api-tests
- Update all schema references so that the commit hash from the release's submodule is used instead of HEAD/master.
- Update all mock data references so that the commit hash from the release's submodule is used instead of HEAD/master.
- Create and push a tag of your branch. Please follow the naming convention:
<module name>-<release version>, e.g.
Module Dependencies and Release Order
In order to satisfy dependencies at time of release, modules need to be released in a particular order.
Generally speaking the precedence looks like:
- Storage modules
- Business logic modules
- UI modules
In some cases there are dependencies between business logic modules which require additional ordering.
TODO: add a dependency graph here showing the acquisitions modules and the interfaces they depend on.
Run release procedure with test run skipping:
mvn -DautoVersionSubmodules=true release:clean release:prepare -Darguments="-Dmaven.test.skip=true -DskipTests"
General best practices - How to structure your NEWS file, what to name your release branches, tags, etc.
- Latest release at the top of the file
- Includes a link to the full changelog (github compare of the previous version tag to this tag)
- Links to JIRA stories/bugs in descending order (highest to lowest)
You may want to separate stories and bugs into separate lists
- Release branches should be named as follows:
- This naming convention will ensure consistency across modules and makes it easily identifiable.
- Release PRs should be named as follows:
<JIRA number> - Release #.#.#
- This naming convention will ensure that the PR is automatically linked to from the JIRA story
MODORDERS-131 - Release 2.0.0
A place to document pitfalls, gotchas, lessons learned in order to help others from repeating the same mistakes etc.
- Creating a tag before allowing others to review your changes will make it more difficult to make changes if any are required. (May only apply to backend modules)
- Removing and re-tagging is known to cause problems with the jenkins. When building the release, jenkins sometimes won't be able to find the tag even though it exists.
- Scrapping the release and moving to the next version creates additional overhead and makes the release notes more confusing.
- API tests: separate branch needs to be created and update any variables to point to release tags
Open Issues and Questions
A place to list open issues for tracking purposes, or ask questions for gathering feedback/comments.