# Release checklist:

## Pre-release tasks

* Figure out whether a release is worthwhile to do.

Tiny/patch releases require some manual work:

* Apply changes to the release branch, merge or cherry-pick
* Append to previous issues_closed_for*md file
* Add new tiny release section to ChangeLog
* Manually adjust versions in json_c_version, CMakeLists.txt, meson.build

The rest of these instructions assume you're creating a minor or major release.

* Load release shell functions
    * `. reltools/reltools.subr`
    * `set_rel_vars`
* Analyze the previous release branch to see if anything should have been
  applied to master.
    * `git log -r "${RELBASE}..${RELBRANCH}" | less`
    * Look for anything other than generating docs, bumping the release
      version, or changes cherry-picked from master.
* Collect changes and assemble tentative release notes.
    * Create "Notes for v0.xx release" page at https://github.com/json-c/json-c/wiki
    * Check commit logs between previous branch point and now for
       notable changes worth mentioning. 
        * `git log --reverse -r "${RELBASE}"..master | less`
    * Create a new issues_closed_for_X.Y.md file
        * `./reltools/gen_issues_closed.md`
        * 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
        * `./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
        * `update_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 GitHub Actions are all working - https://github.com/json-c/json-c/actions
* 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:

    . reltools/reltools.subr
    release=$(get_next_relver)
    cd ${HOME}
    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}:

    # TODO: write me: ./reltools/bump_version.sh --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

        Update the version in meson.build (both at the top, and soversion down under
        '# Build library')

    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

    # Double check that API difference match previous run
    ./abi-check.sh

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

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:

Update master branch version to ${version}.99, in ChangeLog, json_c_version.h, etc...

    git checkout master
    ./reltools/bump_relrease.sh --dev

    # check results, then:
    git push

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

Update the gh-pages branch with new docs (already generated earlier):

    reltag=$(get_most_recent_reltag)
    ./reltools/publish_docs.sh "${reltag}"

    # check results, then:
    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

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

Create a release on GitHub

* https://github.com/json-c/json-c/releases
* Click on "Draft a new release"
* Choose the appropriate tag
* Fill in title, refer to the ChangeLog in the release notes
* Attach the same tarballs as were uploaded to S3
* When satisfied, click Publish release.

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

Send an email to the mailing list.