RELEASE_CHECKLIST.txt

   1
   2 # Release checklist:
   3
   4 ## Pre-release tasks
   5
   6 * Figure out whether a release is worthwhile to do.
   7 * Analyze the previous release branch to see if anything should have been
   8   applied to master.
   9 * Collect changes and assemble tentative release notes.
  10     * Identify previous release branch point
  11     * Check commit logs between previous branch point and now for
  12        notable changes worth mentioning
  13     * Create a new issues_closed_for_X.Y.md file
  14         * Include notable entries from here in the release notes.
  15     * Analyze APIs between previous release branch and master to produce list of
  16       changes (added/removed/updated funcs, etc...), and detect backwards compat
  17       issues.
  18         * https://github.com/lvc/abi-compliance-checker
  19         * See also `abi-check.sh`
  20         * If the new release is not backwards compatible, then this is a MAJOR release.
  21         * Mention removed features in ChangeLog
  22                 * Consider re-adding backwards compatible support, through symbol
  23                   aliases and appropriate entries in json-c.sym
  24                 * Be sure any new symbols are listed in json-c.sym as part of
  25                   the _new_ release version.
  26     * Update the AUTHORS file
  27
  28         PREV=$(git tag | tail -1)
  29         ( git log -r ${PREV}..HEAD | grep Author: | sed -e's/Author: //' ; cat AUTHORS ) | sort -u > A1
  30         mv A1 AUTHORS
  31
  32     * Exclude mentioning changes that have already been included in a point
  33       release of the previous release branch.
  34
  35 * Update ChangeLog with relevant notes before branching.
  36
  37 * Check that the compile works on Linux - automatic through Travis
  38 * Check that the compile works on NetBSD
  39 * Check that the compile works on Windows - automatic through AppVeyor
  40
  41 ## Release creation
  42
  43 Start creating the new release:
  44
  45     PREV=$(git tag | tail -1)
  46     PREV=${PREV#json-c-}
  47     PREV=${PREV%-*}
  48     release=0.$((${PREV#*.} + 1))
  49     cd ~
  50     git clone https://github.com/json-c/json-c json-c-${release}
  51
  52     rm -rf distcheck
  53     mkdir distcheck
  54     cd distcheck
  55     # Note, the build directory *must* be entirely separate from
  56     # the source tree for distcheck to work properly.
  57     cmake -DCMAKE_BUILD_TYPE=Release ../json-c-${release}
  58     make distcheck
  59     cd ..
  60
  61 Make any fixes/changes *before* branching.
  62
  63     cd json-c-${release}
  64     git checkout -b json-c-${release}
  65
  66 ------------
  67
  68 Using ${release}:
  69         Update the version in json_c_version.h
  70         Update the version in CMakeLists.txt (VERSION in the project(...) line)
  71
  72 Update the set_target_properties() line in CmakeLists.txt to set the shared
  73 library version.  Generally, unless we're doing a major release, change:
  74         VERSION x.y.z
  75 to
  76         VERSION x.y+1.z
  77
  78     git commit -a -m "Bump version to ${release}"
  79
  80 If we're doing a major release (SONAME bump), also bump the version
  81  of ALL symbols in json-c.sym.
  82  See explanation at https://github.com/json-c/json-c/issues/621
  83  More info at: https://software.intel.com/sites/default/files/m/a/1/e/dsohowto.pdf
  84
  85 ------------
  86
  87 Generate the doxygen documentation:
  88
  89     (cd ../distcheck && make doc)
  90     cp -r -p ../distcheck/doc/{html,Doxyfile} doc/.
  91         rm doc/Doxyfile   # Remove generated file w/ hardcoded paths
  92     git add -f doc
  93     git commit doc -m "Generate docs for the ${release} release"
  94
  95 ------------
  96
  97 Create the release tarballs:
  98
  99     cd ..
 100     echo .git > excludes
 101     tar -czf json-c-${release}.tar.gz -X excludes json-c-${release}
 102
 103     echo 'doc/*.cmake' >> excludes
 104     echo 'doc/CMakeFiles' >> excludes
 105     echo 'doc/Makefile' >> excludes
 106     echo 'doc/Doxyfile' >> excludes
 107     echo 'doc/html' >> excludes
 108     tar -czf json-c-${release}-nodoc.tar.gz -X excludes json-c-${release}
 109
 110 ------------
 111
 112 Tag the branch:
 113
 114     cd json-c-${release}
 115     git tag -a json-c-${release}-$(date +%Y%m%d) -m "Release json-c-${release}"
 116
 117     git push origin json-c-${release}
 118     git push --tags
 119
 120 ------------
 121
 122 Go to Amazon S3 service at:
 123     https://console.aws.amazon.com/s3/
 124
 125 Upload the two tarballs in the json-c_releases/releases folder.
 126 * Expand "Permissions", pick "Grant public-read access"
 127 * Expand "Properties", ensure "Standard" storage class is picked.
 128
 129 Logout of Amazon S3, and verify that the files are visible.
 130     https://s3.amazonaws.com/json-c_releases/releases/index.html
 131
 132 ===================================
 133
 134 Post-release checklist:
 135
 136     git checkout master
 137
 138 Add new section to ChangeLog for ${release}+1
 139
 140 Use ${release}.99 to indicate a version "newer" than anything on the branch:
 141         Update the version in json_c_version.h
 142         Update the version in CMakeLists.txt
 143
 144 Update RELEASE_CHECKLIST.txt, set release=${release}+1
 145
 146 Add a new empty section to the json-c.sym file, for ${release}+1
 147
 148 Update the set_target_properties() line in CmakeLists.txt to match the release branch.
 149
 150     git commit -a -m "Update the master branch to version ${release}.99"
 151     git push
 152
 153 ------------
 154
 155 Update the gh-pages branch with new docs:
 156
 157     cd json-c-${release}
 158     git checkout json-c-${release}
 159     cd ..
 160
 161     git clone -b gh-pages https://github.com/json-c/json-c json-c-pages
 162     cd json-c-pages
 163     mkdir json-c-${release}
 164     cp -R ../json-c-${release}/doc json-c-${release}/.
 165     git add json-c-${release}
 166     rm json-c-current-release
 167     ln -s json-c-${release} json-c-current-release
 168     git commit -a -m "Add the ${release} docs."
 169
 170     vi index.html
 171     # Add/change links to current release.
 172
 173     git commit -a -m "Update the doc links to point at ${release}"
 174
 175     git push
 176
 177 ------------
 178
 179 Update checksums on wiki page.
 180
 181     cd ..
 182     openssl sha -sha256 json-c*gz
 183     openssl md5 json-c*gz
 184
 185 Copy and paste this output into the wiki page at:
 186 * https://github.com/json-c/json-c/wiki
 187 * https://github.com/json-c/json-c/wiki/Old-Releases
 188
 189 ------------
 190
 191 Send an email to the mailing list.