Rel4tion-Wiki/maint/release.mdwn

Here are the steps for making a release of a Rel4tion software
component/project.

# Git + C/C++

Make sure you're up to date:

	git pull

Make sure you don't have local changes and/or revisions:

	git status

If it's a library project, update the libtool version in `configure.ac` as
needed, depending on how the ABI changed. Update API version too if needed (this
often happens on new major versions). There should be a comment which explains
how to update these versions.

	nano configure.ac

Add a new entry in the `NEWS` file. If needed, look at the git commits since the
previous release, and possibly go over changes in specific files or folders.
Items can be added during the development or just before the release. The format
of NEWS entries depends on the project - see existing projects' NEWS for
examples.

	git log --stat 1.4.1..master     # changes in repo since previous release
	git log --stat 1.4.1..master src # changes in the src directory
	git diff 1.4.1 README            # full diff of README between previous release and current state
	nano NEWS

Configure, build and check. This may take time for large projects, in which case
you can continue to the next step while it's running.

	./autogen.sh      # configure the package
	make              # build the programs, libraries, docs, etc.
	make check        # run tests on them
	make install      # install the built package
	make installcheck # run tests on the installed files
	make distcheck    # make distribution tarball and test it

To avoid waiting for each line to finish, you can run them as a single command
with `&&` between them. When something fails, notice which command it was, so
that you can continue from the right place after fixing it.

When `make distcheck` finishes successfully, it will display a message "ready
for distribution".

Commit the changes you made.

	git commit --message="Release 1.4.2"

Push them. If it fails because someone pushed since you last updated, pull the
updates and repeat your steps.

	git push

Tag the release and push the new tag. For example, if releasing version 1.4.2:

	git tag --sign --message="1.4.2" 1.4.2
	git push origin 1.4.2

Generate documentation for uploading to the website using [[doxygen.css]]. If
the `configure` flags used for the distributed documentation don't generate all
the material, run `configure` with the appropriate flags and build the
documentation. For example, a library project may be distributed with an API
reference and/or tutorial but not full code reference. So you'll need to
generate all these documents:

	./configure --enable-reference=both \
	            --enable-devhelp=both   \
	            --with-ref-css-file=/home/joe/wiki/tools/maintenance/doxygen.css
	make ref

Upload the results to the documentation server. There will be SFTP access for
this soon, but until then send the files to fr33domlover and he will put them in
the right place:

	cd /var/www/doc
	mkdir manual/myproj/1.4.2
	cp --recursive /home/fr33domlover/inbox/myproj-api-1.4.2/* manual/myproj/1.4.2
	mkdir hacking/myproj/1.4.2
	cp --recursive /home/fr33domlover/inbox/myproj-full-1.4.2/* hacking/myproj/1.4.2

Do a post-release version increment in `configure.ac`. A comment there should
explain how.

	nano configure.ac
	git commit --message="Post-release version increment" configure.ac
	git push

Sign the tarball:

	gpg --armor                                         \
	    --comment "http://www.partager.null/people/joe" \
	    --detach-sign                                   \
	    myproj-1.4.2.tar.lz
	mv myproj-1.4.2.tar.lz.asc myproj-1.4.2.tar.lz.sig

Use SCP or SFTP to upload the tarball and the signature to the FTP server.

[[!template id=todo text="explain exactly how"]]

Create 2 DHT-only torrents of the package - one for clearnet and one for I2P.
They don't need to use any trackers and they don't need to have any webseeds.
Just make sure your torrent program supports DHT. The torrent should be a folder
containing two files, like this:

+ myproj-1.4.2
  - myproj-1.4.2.tar.lz
  - myproj-1.4.2.tar.lz.sig

Go to the project's torrents page on the website and add the magnet links of the
new torrents.

Write an announcement page under the project's `news` subpage. Tag it with
`news`, `releases` and the project page itself, e.g. `/projects/myproj`.

	cd /home/joe/wiki
	nano projects/myproj/news/myproj_1.4.2.mdwn
	git commit projects
	git push

Send annoucement to ML, other websites, etc. as needed.

# Darcs + Haskell

Make sure you're up to date:

	$ darcs pull

Make sure you don't have local changes and/or revisions:

	$ darcs whatsnew -sl

If it's a library project, update the version in `myproj.cabal` as
needed, according to the Package Versioning Policy.

	$ vim myproj.cabal

Add a new entry in the `NEWS` file. If needed, look at the darcs records since
the previous release, and possibly go over changes in specific files or
folders. Items can be added during the development or just before the release.
The format of NEWS entries depends on the project - see existing projects' NEWS
for examples.

	$ darcs changes --from-tag 1.4.0.1     # changes in repo since previous release
	$ darcs changes --from-tag 1.4.0.1 src # changes in the src directory
	$ darcs diff --from-tag 1.4.0.1 README # full diff of README between previous release and current state
	$ vim NEWS

Configure, build and check. This may take time for large projects, in which
case you can continue to the next step while it's running.

	$ cabal configure --enable-tests # configure the package
	$ cabal build                    # build the programs, libraries, etc.
	$ cabal test                     # run tests on them
	$ cabal check                    # run cabal tests
	$ cabal sdist                    # make distribution tarball

To avoid waiting for each line to finish, you can run them as a single command
with `&&` between them. When something fails, notice which command it was, so
that you can continue from the right place after fixing it.

Generate documentation and browse it to test:

	$ cabal haddock
	$ elinks dist/doc/html/text-position/index.html

Documentation of dependencies, needed for linking, may be missing. You can
install documentation using `cabal install --enable-documentation mydep`.

Record the changes you made.

	$ darcs record --name="Release 1.4.1.0"

Push them. If it fails because someone pushed since you last updated, pull the
updates and repeat your steps.

	$ darcs push

Tag the release and push the new tag. For example, if releasing version
1.4.1.0:

	$ darcs tag 1.4.1.0
	$ darcs push

Sign the tarball:

	gpg --armor                                    \
	    --comment "http://rel4tion.org/people/joe" \
	    --detach-sign                              \
	    dist/myproj-1.4.1.0.tar.gz
	mv myproj-1.4.1.0.tar.gz.asc myproj-1.4.1.0.tar.gz.sig

Use SCP or SFTP to upload the tarball and the signature to the FTP server.

[[!template id=todo text="explain exactly how"]]

Create a DHT torrent:

+ myproj-1.4.1.0
  - myproj-1.4.1.0.tar.gz
  - myproj-1.4.1.0.tar.gz.sig

Go to the project's torrents page on the website and add the magnet links of the
new torrents.

Write an announcement page under the project's `news` subpage. Tag it with
`news`, `releases` and the project page itself, e.g. `/projects/myproj`.

	$ cd /home/joe/wiki
	$ nano projects/myproj/news/myproj_1.4.1.0.mdwn
	$ git commit projects
	$ git push

Send annoucement to ML, other websites, etc. as needed.