Coding Standards

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

Please try and stick to the GNU coding standards.  A lot of hard work

went into making Check compatible with the standards, and would be

nice if that work didn't erode.  I decided on the standards because

they work well for a lot of programs much bigger than Check.  Ok,

since you're wondering, the advantages of sticking to the standards

are three-fold:

  1) consistent style within the project

  2) being familiar with the standards lets you work on lots of

     different GNU standards-compliant projects pretty easily

  3) it reduces the number of decisions that must be made

Release Process

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

To create a release one will need to be a member of the libcheck organization

on GitHub. If you are not a member, a current member can add you

by going to:

   https://github.com/orgs/libcheck/people

and submitting an invite.

1) To create a release, start in a configured in-place

checkout of the Check project:

$ git clone https://github.com/libcheck/check.git

$ cd check

2) Determine the version of Check to release, and update

the configure.ac script:

AC_INIT([Check], [0.10.1], [check-devel at lists dot sourceforge dot net])

CHECK_MAJOR_VERSION=0

CHECK_MINOR_VERSION=10

CHECK_MICRO_VERSION=1

(Remember to update both the AC_INIT line and each of the CHECK_*_VERSION fields).

3) Update the header in the NEWS file to mention the release:

Sun Aug 2, 2015: Released Check 0.10.1

  2015-08-02 19:21:14 +0000

  based on hash f399542eeceb97703bca496b68bb39044e8baa01

4) Update index.html mentioning the release. Look for the following:

5) Attempt to build the release locally

$ autoreconf -i

$ ./configure

$ make distcheck

If this passes, a tarball with the current release number will be in the current

directory. Make note of this, as it will be uploaded to GitHub later.

6) Commit the changes to configure.ac, NEWS, and index.html to the Check project's

master branch, with the commit message:

"Update for release"

7) Log On to GitHub and navigate to:

https://github.com/libcheck/check/releases

Click "Draft a New Release".

Enter the release version to the Tag Version box, and enter the

git hash into the Target selector.

Fill in the Release Title field.

Describe the release with something similar to the following:

=====

<some sentence about the release, e.g. "This is a bug fix release.">

Please test it out and report any problems you might have.

Changes:

<paste contents of NEWS here for the release>

=====

Attach the tarball for the release, then publish the release.

8) Use the following template to announce the release via email:

=====

Subject: check-X.Y.Z released

Hi,

<some sentence about the release, e.g. "This is a bug fix release."> 

Please test it out and report any problems you might have.

https://github.com/libcheck/check/releases

Thanks,

`whoami`

<paste contents of NEWS for the release here>

=====

9) Update the development header in the NEWS file and commit the result.

10) Push updated website (see section below)

Congratulations, you are done!

Update website

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

The Check website is automatically hosted from the contents of

the gh-pages branch in the Check git repository. To update

the website, merge the contents of the master branch into

the gh-pages branch.

To update the generated documentation for the website:

$ git remote -v

github  https://github.com/libcheck/check.git (fetch)

github  https://github.com/libcheck/check.git (push)

$ git fetch github

$ git checkout github/gh-pages -b gh-pages

Branch gh-pages set up to track remote branch gh-pages from github.

Switched to a new branch 'gh-pages'

$ git merge github/master

First, rewinding head to replay your work on top of it...

Fast-forwarded gh-pages to github/master.

$ autoreconf -i

$ ./configure

$ make clean

$ make

$ make doc/check_html

$ make doc/doxygen

$ git add doc

$ git commit -m “Update documentation”

$ git push github gh-pages:gh-pages

Automatic building of pull requests

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

The GitHub project is configured to build pull requests either when

asked or automatically. This is done using the GitHub Pull Request

Builder Plugin. Documentation here:

   https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin

When a new pull request is opened in the project and the author of the pull request

isn't white-listed, builder will ask "Can one of the admins verify this patch?".

An admin can add one of the following comments to the pull request:

   "ok to test" to accept this pull request for testing

   "test this please" for a one time test run

   "add to whitelist" to add the author to the whitelist

If the build fails for other various reasons you can rebuild.

   "retest this please" to start a new build

When a build is triggered a job on the Jenkins instance will start:

   https://check.ci.cloudbees.com/job/github-merge-builder/

When complete, a comment will be added to the pull request, informing

of the result.

An admin can be added to the Jenkins instance by adding a username

to the "Admin list" setting under the "GitHub Pull Request Builder"

section here:

   https://check.ci.cloudbees.com/configure

This works because there is a user in the libcheck organization,

"check-builder", which the Jenkins instance uses to install a

git hook and push comments to pull requests.

Using gcov

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

The gcov tool can be used to determine the unit test coverage in Check

itself. This is currently supported on GNU/Linux only. To enable the

necessary build time flags, add the following argument to the

configure script:

   --enable-gcov

Once the unit tests have been run with

$ make check

assuming the terminal is in the top src directory, the following will

generate summary information using gcov:

$ cp src/*.c src/.libs/

$ cd src/.libs

$ for file in `ls *.c`; do

   gcov -f $file > $file.gcov.summary.txt

   mv $file.gcov $file.gcov.txt

  done

The *.gcov.txt files will contain the source code annotated with

the number of times each line was executed. The .*gcov.summary.txt

files will contain a line execution summary per function.

To determine the line execution summary for all of Check, either

the gcovr tool can be used, or the following quick-and-dirty script:

$ for file in ls *.summary.txt; do cat $file; done \

  | grep "Lines executed" | cut -d ":" -f 2 | tr -d "%" \

  | awk '{checked+=$1*$3/100; total+=$3} END {print checked/total*100}'