RELEASE

This describes what to do for an release!

= Info =

Following shell expansions are used in this document:
 ~e           .. source of libelektra
 ~build       .. the build directory
 ~elektra     .. the directory above ~e and ~build
 ~elektra-ftp .. where ftp files go to
 ~elektra-doc .. where doc flies go to


= TODO =

- make sure no TODO is in this file (resolve them first!)
- Simplify release!
- Scripts for strace, version, run tests!
- Check transitions in plugin status: especially from/to experimental
- Check if Elektra builds, installs and works on freshly installed OS

== Testing ==

- fuzz checker
- memleaks
- ASAN




= Tasks before Release =

== Updates ==

- Update doc/COMPILE.md to reflect actually tested setups
- Update/run ~e/scripts/build-debian-package
- Update contracts using update-infos-status
- regenerate dot of plugins using scripts/draw-all-plugins
- run link checker: cd ~build && ~e/scripts/link-checker external-links.txt

== Increment Version Number ==

Increment version numbers in

- CMakeLists.txt
- ~e/scripts/build-debian-package
- Change VERSION variable in build-server


export VERSION=`kdb get system/elektra/version/constants/KDB_VERSION`
export DVERSION=$VERSION-1
 dch --newversion $DVERSION "New upstream version."
 git-add debian/changelog
 git-commit -m "Debian Package $DVERSION (UNRELEASED)"


== Cleanup ==

For the first few steps you have to work on branch master:
 git-checkout master

If any feature branch is left over merge it:
 git-merge --no-ff feature

And now commit everything:
 git-commit -a

Clean up the mess left over:
 git-clean -dfx

Make an empty builddirectory:
 mkdir ~build



== Check ==

Try to move as much as possible from this manual checks to build-server!

Before release is done, following must be checked:
- Everything blue on https://build.libelektra.org/

If version numbers are correct in
- CMakeLists.txt

  mkdir ~elektra/$VERSION && kdb --version > ~elektra/$VERSION/version

Rebuild cleanly, run all tests and also check for memleaks:
  cd ~build && ~e/scripts/configure-debian ~e && make -j5 && make run_all -j5 && make run_memcheck -j5

Check if there are really >=241 or >=131 tests

- Log tests:
  kdb run_all -v > ~elektra/$VERSION/run_all 2>&1

- Check binary compatibility
  Install libelektra-test of the previous version and run again:

  CHECK_VERSION=NO kdb run_all > ~elektra/$VERSION/run_all_version  2>&1

- Check which files changed

  DESTDIR=D make install -j5
  cd ~build/D && find . | sort > ~elektra/$VERSION/installed_files

- Check library

  ls -l /usr/lib/x86_64-linux-gnu/libelektra-core.so.$VERSION  > ~elektra/$VERSION/size
  readelf -a /usr/lib/x86_64-linux-gnu/libelektra-core.so > ~elektra/$VERSION/readelf-core


Check if [doc/todo/API] is fulfilled





= Preperation =

Set environment variable VERSION to current version (assumed its already locally installed) to make the
commands below work for copy&paste:

 export VERSION=`kdb get system/elektra/version/constants/KDB_VERSION`


== Tag the version ==

 git tag --sign $VERSION -m "Release $VERSION"


== Prepare Source Package ==

Build tar.gz:
 cd ~build && make source-package

Check if tar is reproduceable + sign it:
 gpg --sign elektra-$VERSION.tar.gz

Unpack + compile (with all available plugins) + test those sources:
 tar xvzf elektra-$VERSION.tar.gz && mkdir builder
 cd ~build/builder && ~e/scripts/configure-debian ../elektra-$VERSION && make -j5 && make run_all && make run_memcheck

Now copy the packages to ftp:
 cp ~build/elektra-$VERSION.tar.gz* ~elektra-ftp/releases
 cp ~elektra-ftp/releases/elektra-$VERSION.tar.gz ~elektra/$VERSION/


== Debian Package ==

export DVERSION=$VERSION-1

Build deb:
 cd ~e && git-checkout debian
 git-merge --no-ff $VERSION -m "Merge for debian release $DVERSION"

UNRELEASED -> unstable

 dch --release $DVERSION "New upstream version"
 git-add debian/changelog
 git-commit -m "Debian Package $DVERSION"

Fix debian/ + document in NEWS what maintainer need to consider, then build the package:
 cp ~elektra-ftp/releases/elektra-$VERSION.tar.gz ~elektra/elektra_$VERSION.orig.tar.gz
 git clean -fdx && gpg -u0B2F0DDC --sign `mktemp` # so that the step afterwards won't abort
 gbp buildpackage -rfakeroot -k0B2F0DDC -sa

Now move and install:
 cd ~elektra && mkdir -p ~elektra/$VERSION/debian/$DVERSION
 mv elektra_$DVERSION* *$DVERSION*.deb elektra_$VERSION.orig.tar.gz ~elektra/$VERSION/debian/$DVERSION/
 sudo dpkg -i ~elektra/$VERSION/debian/$DVERSION/*`dpkg-architecture -qDEB_BUILD_ARCH`.deb


Run some basic commands, at least:
 kdb --version | tee ~elektra/$VERSION/version
 kdb qt-gui

Strace what tools are doing:

 strace -o ~elektra/$VERSION/mount.strace kdb mount file.ecf user/release_test
 strace -o ~elektra/$VERSION/file.strace kdb file user/release_test/b
 strace -o ~elektra/$VERSION/set.strace kdb set user/release_test/b
 strace -o ~elektra/$VERSION/get.strace kdb get user/release_test/b
 strace -o ~elektra/$VERSION/rm.strace kdb rm user/release_test/b
 strace -o ~elektra/$VERSION/umount.strace kdb umount user/release_test

Run tests:

 KDB=kdb kdb run_all -v | tee ~elektra/$VERSION/run_all 2>&1
 KDB=kdb-full kdb-full run_all | tee ~elektra/$VERSION/run_all_full 2>&1

Install libelektra-test of the previous version and run again:

 CHECK_VERSION=NO kdb run_all -v > ~elektra/$VERSION/run_all_abi 2>&1


== Test external tools ==


Check if tools based on Elektra still do:
 dq

Run unit-tests in-source again (because some use installed Elektra):
 make run_all


== Test external test suites ==

#https://github.com/oyranos-cms/oyranos/blob/master/src/tests/test2.cpp#L185
#https://github.com/oyranos-cms/oyranos/blob/master/src/liboyranos_config/oyranos_elektra.c#L195

git clone git@github.com:oyranos-cms/oyranos.git
cd oyranos
mkdir build
cd build
cmake .. # might fail, simply comment out missing libs
make -j5 # not needed
make test2 # or make test-2 for the most of the tests
src/tests/test2 Elektra


== Documentation ==

And the API docu:
 mkdir ~elektra-doc/api/$VERSION/
 cd ~build && cmake -DBUILD_PDF=ON . && rm -rf doc && make html man && cp -ra doc/html doc/latex doc/man ~elektra-doc/api/$VERSION/

Symlink current to latest version and add everything:
 cd ~elektra-doc/api/ && rm current && ln -s $VERSION current && git-add current $VERSION && git-commit -a -m "$VERSION Release"




= Publish =

== Debian Package ==

 cd ~elektra/$VERSION/debian/$DVERSION && reprepro --ignore=wrongdistribution include stretch elektra_${DVERSION}_`dpkg-architecture -qDEB_BUILD_ARCH`.changes && update-reprepro

== Commit source package ==

Commit elektra-ftp:
 cd ~elektra-ftp && git-add releases/elektra-$VERSION.tar.gz* && git-commit -a -m "Release $VERSION"


== push ==

Now we know that everything worked well:

Now push release branch with tags to github:
 cd ~e && git-push && git-push --tags

Push elektra-ftp:
 cd ~elektra-ftp && git push && git push github

Push elektra-doc to github:
 cd ~elektra-doc && git push && git push github


== prep for next release ==

cd ~e && cp doc/todo/NEWS.md doc/news/_preparation_next_release.md

increment CMPVERSION in scripts/run_icheck
increment VERSION in scripts/build-debian-package
and cleanup tests/icheck.suppression


== Announce ==

Finish NEWS.md for new release (hashsum, add links where to download release, check them):
 scripts/generate-hashsums ~elektra-ftp/releases/elektra-$VERSION.tar.gz
 editor doc/news/*$VERSION*.md

Finally send out mail to list
(Personal notice: see also NOTIFY)