json-c/RELEASE_CHECKLIST.txt

# Release checklist:

## Pre-release tasks

* Figure out whether a release is worthwhile to do.
* Analyze the previous release branch to see if anything should have been
  applied to master.
* Collect changes and assemble tentative release notes.
    * Identify previous release branch point
    * Check commit logs between previous branch point and now for
       notable changes worth mentioning
    * Create a new issues_closed_for_X.Y.md file
        * Include notable entries from here in the release notes.
    * Analyze APIs between previous release branch and master to produce list of
      changes (added/removed/updated funcs, etc...), and detect backwards compat
      issues.
        * https://github.com/lvc/abi-compliance-checker
        * See also `abi-check.sh`
        * If the new release is not backwards compatible, then this is a MAJOR release.
        * Mention removed features in ChangeLog
		* Consider re-adding backwards compatible support, through symbol
		  aliases and appropriate entries in json-c.sym
		* Be sure any new symbols are listed in json-c.sym as part of
		  the _new_ release version.
    * Update the AUTHORS file

        PREV=$(git tag | tail -1)
        ( git log -r ${PREV}..HEAD | grep Author: | sed -e's/Author: //' ; cat AUTHORS ) | sort -u > A1
        mv A1 AUTHORS

    * Exclude mentioning changes that have already been included in a point 
      release of the previous release branch.

* Update ChangeLog with relevant notes before branching.

* Check that the compile works on Linux - automatic through Travis
* Check that the compile works on NetBSD
* Check that the compile works on Windows - automatic through AppVeyor

## Release creation

Start creating the new release:

    PREV=$(git tag | tail -1)
    PREV=${PREV#json-c-}
    PREV=${PREV%-*}
    release=0.$((${PREV#*.} + 1))
    cd ~
    git clone https://github.com/json-c/json-c json-c-${release}

    rm -rf distcheck
    mkdir distcheck
    cd distcheck
    # Note, the build directory *must* be entirely separate from
    # the source tree for distcheck to work properly.
    cmake -DCMAKE_BUILD_TYPE=Release ../json-c-${release}
    make distcheck
    cd ..

Make any fixes/changes *before* branching.

    cd json-c-${release}
    git checkout -b json-c-${release}

------------

Using ${release}:
	Update the version in json_c_version.h
	Update the version in CMakeLists.txt (VERSION in the project(...) line)

Update the set_target_properties() line in CmakeLists.txt to set the shared
library version.  Generally, unless we're doing a major release, change:
	VERSION x.y.z
to
	VERSION x.y+1.z

    git commit -a -m "Bump version to ${release}"

If we're doing a major release (SONAME bump), also bump the version
 of ALL symbols in json-c.sym.
 See explanation at https://github.com/json-c/json-c/issues/621
 More info at: https://software.intel.com/sites/default/files/m/a/1/e/dsohowto.pdf

------------

Generate the doxygen documentation:

    (cd ../distcheck && make doc)
    cp -r -p ../distcheck/doc/{html,Doxyfile} doc/.
	rm doc/Doxyfile   # Remove generated file w/ hardcoded paths
    git add -f doc
    git commit doc -m "Generate docs for the ${release} release"

------------

Create the release tarballs:

    cd ..
    echo .git > excludes
    tar -czf json-c-${release}.tar.gz -X excludes json-c-${release}

    echo 'doc/*.cmake' >> excludes
    echo 'doc/CMakeFiles' >> excludes
    echo 'doc/Makefile' >> excludes
    echo 'doc/Doxyfile' >> excludes
    echo 'doc/html' >> excludes
    tar -czf json-c-${release}-nodoc.tar.gz -X excludes json-c-${release}

------------

Tag the branch:

    cd json-c-${release}
    git tag -a json-c-${release}-$(date +%Y%m%d) -m "Release json-c-${release}"

    git push origin json-c-${release}
    git push --tags

------------

Go to Amazon S3 service at:
    https://console.aws.amazon.com/s3/

Upload the two tarballs in the json-c_releases/releases folder.
* Expand "Permissions", pick "Grant public-read access"
* Expand "Properties", ensure "Standard" storage class is picked.

Logout of Amazon S3, and verify that the files are visible.
    https://s3.amazonaws.com/json-c_releases/releases/index.html

===================================

Post-release checklist:

    git checkout master

Add new section to ChangeLog for ${release}+1

Use ${release}.99 to indicate a version "newer" than anything on the branch:
	Update the version in json_c_version.h
	Update the version in CMakeLists.txt

Update the set_target_properties() line in CmakeLists.txt to match the release branch.

Add a new empty section to the json-c.sym file, for ${release}+1

    git commit -a -m "Update the master branch to version ${release}.99"
    git push

------------

Update the gh-pages branch with new docs:

    cd json-c-${release}
    git checkout json-c-${release}
    cd ..

    git clone -b gh-pages https://github.com/json-c/json-c json-c-pages
    cd json-c-pages
    mkdir json-c-${release}
    cp -R ../json-c-${release}/doc json-c-${release}/.
    git add json-c-${release}
    rm json-c-current-release
    ln -s json-c-${release} json-c-current-release
    git commit -a -m "Add the ${release} docs."

    vi index.html
    # Add/change links to current release.

    git commit -a -m "Update the doc links to point at ${release}"

    git push

------------

Update checksums on wiki page.

    cd ..
    openssl sha1 -sha256 json-c*gz
    openssl md5 json-c*gz

Copy and paste this output into the wiki page at:
* https://github.com/json-c/json-c/wiki
* https://github.com/json-c/json-c/wiki/Old-Releases

------------

Send an email to the mailing list.