Standard for Public Code

Contents

Releasing a new version of the Standard for Public Code

  1. Review state of the ‘develop’ branch
    • Ensure all changes intended for release are merged
    • Invite a proofread of the current state of the branch
      • If new dashes are introduced, check if the language can be simplified to remove them in favor of more simple sentences. If a complex sentence is needed, see if the dash can be replaced with other punctuation. If a dash is truly the best expression of ideas, then follow the Chicago Manual of Style.
  2. Create a release branch
    • From ‘develop’, git switch -c "release-$MAJOR.$MINOR.$PATCH"
    • Push the branch, git push -u origin release-$MAJOR.$MINOR.$PATCH
    • Open a DRAFT pull request from the new branch in to main so that others can easily review, discuss, and add commits to the branch
  3. Update the new release
    • Update AUTHORS.md with new contributors
    • Update CHANGELOG.md
    • Update roadmap.md
    • Perform extra pass on diff to the ‘main’ branch
      • run script/generate-review-template.sh and commit updated docs/review-template.html
      • update docs/standard-for-public-code.html with the new text from the review template, updating any status changes as a result
      • Reread any section or paragraph to ensure wording changes still fit the whole and do not contain grammar or spelling errors
      • Ensure fonts are installed, see: script/ensure-font.sh
      • Check the rendered .pdf using script/pdf.sh rc1
        • Ensure no link collisions exist
        • Check the page breaks, possibly removing or adding page-break CSS, for example: <p style="page-break-after: always;"></p>
      • If needed, commit fixes and repeat extra pass
    • Push branch, compare with ‘main’ branch, i.e.: https://github.com/standard-for-public-code/standard-for-public-code/compare/main...release-$MAJOR.$MINOR.$PATCH
      • Request review from multiple reviewers, especially a proofreader
      • Reviewers will create issues for shortcomings found which would not prevent release
      • If needed for release, reviewers may create pull requests to resolve issues
      • Re-request reviews if additional pull requests are merged into release branch
    • Run the to-archive-org.sh script
  4. Create GitHub release with the release notes and version number
    • git tag trigger-$MAJOR.$MINOR.$PATCH
    • git push --tags (see: ../.github/workflows/release-on-tag.yml); this will close the DRAFT pull request
    • delete local tag: git tag -d trigger-$MAJOR.$MINOR.$PATCH
  5. Send the files for print to the printer for the book, and checklist
    • Cover file: standard-cover-$MAJOR.$MINOR.$PATCH.pdf
    • Inside pages PDF: standard-for-public-code-print-$MAJOR.$MINOR.$PATCH.pdf
    • Folded checklist: standard-checklist-folded-$MAJOR.$MINOR.$PATCH.pdf
  6. Ping translation contributors