Home

Onboarding New Developers for Project Maintenance

• Create a new GitHub account or provide the account to a current maintainer
• Review and sign the NIST GitHub Rules of Behavior form to join the the usnistgov organization on GitHub.
• Follow the instructions in the form and submit it to the correct point of contact.
• Request a current maintainer add the GitHub account to the itl-oscal-admins team in the usnistgov organization in GitHub.
• Create a new account on issues.sonatype.org.
• Request a current maintainer endorse a ticket you create to added to the correct group for this package namespace. (Example: OSSRH-88618).
• Review README.md for how to proceed.

Release Procedures

• Rebase develop branch on main to ensure future linear commit history: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && pushd liboscal-java && git checkout --track origin/develop && git pull -r origin main.
• Run the maven to prepare the release: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && pushd liboscal-java && git checkout --track origin/develop && mvn release:clean release:prepare.
• Once this is complete, sync remote state so develop will be pointing to the latest snapshot release and the new release tag (not a GitHub release yet): git checkout develop && git push --follow-tags
• Once the tagged version is completed for the associated release, merge the tag and release prep into main branch to finish the release: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && pushd liboscal-java && git checkout --track origin/main && git merge --ff-only v0x.y.z && git push origin HEAD.
• Release automation in GitHub Actions will the build the snapshot release and final release in GitHub Actions.
• Once complete review the appropriate release in Sonatype OSS repository and close it to prepare for promotion.
  
  
• Once steps complete, promote the closed release with the release action.
  
  
• Go to the releases section and create the release notes based on the new 0x.y.z tag.
• Ensure develop branch is based off main for linear commits on future releases: git checkout develop && git pull -r origin main.
• Communicate release to the community
  • Coordinate with the outreach director to take the release notes and publish them to the OSCAL Lobby community channel in Gitter.
  • Coordinate with the outreach director to take the release notes and publish them to oscal-dev@list.nist.gov and oscal-updates@list.nist.gov.
  • Update the news page with a PR to the news page on the content site and publish it. usnistgov/OSCAL-Pages#52 is a good example PR.

Release Rollback Procedures

Sometimes a release doesn't go as planned or a change must be made before a release if finalized. In GitHub and our usage, a release must be associated with a tag, so we must delete the tag, remove commits, and re-release with the above in emergency situations.

• Update the development environment on the target branch, likely develop: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && git clone git@github.com:usnistgov/liboscal-java.git && pushd liboscal-java && git fetch --tags && git checkout --track origin/develop
• Delete a pre-existing tag for the release to be rolled back: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && git tag --delete vX.Y.Z && git push --delete origin vX.Y.Z
• If necessary and you have made invalid commits with the Maven plugins that begin with [maven determine how many commits you must remove from the target branch to rollback the release. You will use this in the next step. Count the number of commits before, not including the commit you want to keep. That will be N below.
• Remove commits from target branch, likely develop: git remote set-url origin git@github.com:usnistgov/liboscal-java.git && git checkout develop && git reset --hard origin/develop && git reset --hard HEAD~N # N is the number commits before the commit you keep, do not include it && git push origin HEAD -f
• Re-run release procedures.