granicus.if.org Git - check/blob - HACKING

   1 Coding Standards
   2 ================
   3
   4 Please try and stick to the GNU coding standards.  A lot of hard work
   5 went into making Check compatible with the standards, and would be
   6 nice if that work didn't erode.  I decided on the standards because
   7 they work well for a lot of programs much bigger than Check.  Ok,
   8 since you're wondering, the advantages of sticking to the standards
   9 are three-fold:
  10
  11   1) consistent style within the project
  12
  13   2) being familiar with the standards lets you work on lots of
  14      different GNU standards-compliant projects pretty easily
  15
  16   3) it reduces the number of decisions that must be made
  17
  18 Doxygen Reference for Development
  19 ================
  20
  21 You can use `doc/doxygen-devel` target to generate a verbose doxygen reference.
  22 Resulting documentation will be placed into `doc/doxygen-devel`. This option
  23 needs graphviz installed to render call graphs. If graphviz is not found they
  24 won't be rendered.
  25
  26 Release Process
  27 ===============
  28
  29 To create a release one will need to be a member of the libcheck organization
  30 on GitHub. If you are not a member, a current member can add you
  31 by going to:
  32    https://github.com/orgs/libcheck/people
  33 and submitting an invite.
  34
  35 1) To create a release, start in a configured in-place
  36 checkout of the Check project:
  37
  38 $ git clone https://github.com/libcheck/check.git
  39 $ cd check
  40
  41 2) Determine the version of Check to release, and update
  42 the configure.ac script:
  43
  44 AC_INIT([Check], [0.10.1], [check-devel at lists dot sourceforge dot net])
  45 CHECK_MAJOR_VERSION=0
  46 CHECK_MINOR_VERSION=10
  47 CHECK_MICRO_VERSION=1
  48
  49 (Remember to update both the AC_INIT line and each of the CHECK_*_VERSION fields).
  50
  51 3) Update the header in the NEWS file to mention the release:
  52
  53 Sun Aug 2, 2015: Released Check 0.10.1
  54   2015-08-02 19:21:14 +0000
  55   based on hash f399542eeceb97703bca496b68bb39044e8baa01
  56
  57 4) Update index.html mentioning the release. Look for the following:
  58 <!-- Update this section during a release -->
  59
  60 5) Attempt to build the release locally
  61
  62 $ autoreconf -i
  63 $ ./configure
  64 $ make distcheck
  65
  66 If this passes, a tarball with the current release number will be in the current
  67 directory. Make note of this, as it will be uploaded to GitHub later.
  68
  69 6) Commit the changes to configure.ac, NEWS, and index.html to the Check project's
  70 master branch, with the commit message:
  71 "Update for release"
  72
  73 7) Log On to GitHub and navigate to:
  74
  75 https://github.com/libcheck/check/releases
  76
  77 Click "Draft a New Release".
  78
  79 Enter the release version to the Tag Version box, and enter the
  80 git hash into the Target selector.
  81
  82 Fill in the Release Title field.
  83
  84 Describe the release with something similar to the following:
  85 =====
  86 <some sentence about the release, e.g. "This is a bug fix release.">
  87 Please test it out and report any problems you might have.
  88
  89 Changes:
  90 <paste contents of NEWS here for the release>
  91 =====
  92
  93 Attach the tarball for the release, then publish the release.
  94
  95 8) Use the following template to announce the release via email:
  96 =====
  97 Subject: check-X.Y.Z released
  98 Hi,
  99
 100 <some sentence about the release, e.g. "This is a bug fix release.">
 101 Please test it out and report any problems you might have.
 102
 103 https://github.com/libcheck/check/releases
 104
 105 Thanks,
 106 `whoami`
 107
 108 <paste contents of NEWS for the release here>
 109 =====
 110
 111 9) Update the development header in the NEWS file and commit the result.
 112
 113 10) Push updated website (see section below)
 114
 115 Congratulations, you are done!
 116
 117
 118 Update website
 119 ==============
 120
 121 The Check website is automatically hosted from the contents of
 122 the gh-pages branch in the Check git repository. To update
 123 the website, merge the contents of the master branch into
 124 the gh-pages branch.
 125
 126 To update the generated documentation for the website:
 127
 128 $ git remote -v
 129 github  https://github.com/libcheck/check.git (fetch)
 130 github  https://github.com/libcheck/check.git (push)
 131 $ git fetch github
 132 $ git checkout github/gh-pages -b gh-pages
 133 Branch gh-pages set up to track remote branch gh-pages from github.
 134 Switched to a new branch 'gh-pages'
 135 $ git merge github/master
 136 First, rewinding head to replay your work on top of it...
 137 Fast-forwarded gh-pages to github/master.
 138 $ autoreconf -i
 139 $ ./configure
 140 $ make clean
 141 $ make
 142 $ make doc/check_html
 143 $ make doc/doxygen
 144 $ git add doc
 145 $ git commit -m “Update documentation”
 146 $ git push github gh-pages:gh-pages
 147
 148
 149 Automatic building of pull requests
 150 ===============
 151
 152 The GitHub project is configured to build pull requests either when
 153 asked or automatically. This is done using the GitHub Pull Request
 154 Builder Plugin. Documentation here:
 155
 156    https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin
 157
 158 When a new pull request is opened in the project and the author of the pull request
 159 isn't white-listed, builder will ask "Can one of the admins verify this patch?".
 160
 161 An admin can add one of the following comments to the pull request:
 162    "ok to test" to accept this pull request for testing
 163    "test this please" for a one time test run
 164    "add to whitelist" to add the author to the whitelist
 165
 166 If the build fails for other various reasons you can rebuild.
 167
 168    "retest this please" to start a new build
 169
 170 When a build is triggered a job on the Jenkins instance will start:
 171
 172    https://check.ci.cloudbees.com/job/github-merge-builder/
 173
 174 When complete, a comment will be added to the pull request, informing
 175 of the result.
 176
 177 An admin can be added to the Jenkins instance by adding a username
 178 to the "Admin list" setting under the "GitHub Pull Request Builder"
 179 section here:
 180
 181    https://check.ci.cloudbees.com/configure
 182
 183 This works because there is a user in the libcheck organization,
 184 "check-builder", which the Jenkins instance uses to install a
 185 git hook and push comments to pull requests.
 186
 187
 188 Using gcov
 189 ===============
 190
 191 The gcov tool can be used to determine the unit test coverage in Check
 192 itself. This is currently supported on GNU/Linux only. To enable the
 193 necessary build time flags, add the following argument to the
 194 configure script:
 195
 196    --enable-gcov
 197
 198 Once the unit tests have been run with
 199
 200 $ make check
 201
 202 assuming the terminal is in the top src directory, the following will
 203 generate summary information using gcov:
 204
 205 $ cp src/*.c src/.libs/
 206 $ cd src/.libs
 207 $ for file in `ls *.c`; do
 208    gcov -f $file > $file.gcov.summary.txt
 209    mv $file.gcov $file.gcov.txt
 210   done
 211
 212 The *.gcov.txt files will contain the source code annotated with
 213 the number of times each line was executed. The .*gcov.summary.txt
 214 files will contain a line execution summary per function.
 215
 216 To determine the line execution summary for all of Check, either
 217 the gcovr tool can be used, or the following quick-and-dirty script:
 218
 219 $ for file in ls *.summary.txt; do cat $file; done \
 220   | grep "Lines executed" | cut -d ":" -f 2 | tr -d "%" \
 221   | awk '{checked+=$1*$3/100; total+=$3} END {print checked/total*100}'