HFST Coding style and best common practices

This file contains information on coding conventions, and guidelines for implementation. When contributing code to project, try to follow it whenever possible.

Warning, important while this file suggests best common practices for contributors, it isn't enforced, so you'll find tons of non-conformant code and documentation. When modifying broken code or documentation, you may either fix the whole file or just attempt to write more of the broken data to maintain uniformity.

Coding style

Coding style is not currently enforced, but it is suggested that authors follow or acknowledge GNU coding style guidelines and C++ coding style for C and C++ parts, SUN coding conventions for Java parts, PEP8 for python parts, and so on. But more important than following certain guidelines is being consistent.

The users of vim must use cindent with settings: cinoptions=>4,n-2,f2,{2,^-2,:2,=2,t0,(0,u0,w1,m1, and autoindent and file type indentation rules at all times.

The users of emacs should also turn on automatic indentation and disable the use of tabs for indentation. This is extremely tricky in C programming mode so pay close attention to it!

At the very least you must stick to maximum line length of 79 (80), and use some indentation with spaces.

Version control usage

All changes should be commited to version control system, ideally one change at a time. Each commit must be accompanied by meaningful commit message summarising change(s) in English. Commit logs are collected to ChangeLog on each release using scripts, such as svn2cl. Good ChangeLog message conventions are detailed in the GNU coding style guidelines.

Do not commit anything that won’t pass make.

Releasing

The following should be verified to be in order for a release to be made:

  1. make check passes. Make check should be running all the unit tests and test scripts available.
  2. make dist produces a distributable archive.
  3. Generated documentation gets generated and is complete.
  4. The archive is installable and make check passes in a local directory (./configure --prefix=$PATH_TO_LOCAL_DIR).
  5. The archive is installable and make check passes in a clean chroot or machine without any previously installed HFST library.
  6. The distributed tools are basically usable in the above-mentioned scenarios.
  7. The library can be successfully linked to in order to produce a toy utility, eg. from HFST's API documentation

Making a release of hfst (same as any FLOSS project, basically)

When a HFST source tree is considered stable and usable enough to inflict it upon wider audiences than the version control tree (which is meant for early adopters and testers who know things are segfaulting buggy concoctions over there), a certain number of upkeeping rituals needs to be done.

Firstly ensuring that everything is in place and seemingly workable:

$ svn co https://svn.hfst.sourceforge.net/svnroot/hfst/trunk/hfst??? \
hfst???-releasetest
[...]
$ cd hfst???-releasetest
$ autoreconf -i
$ ./configure
$ make distcheck
$ scp hfst???.tar.gz another-machine:.
$ ssh another-machine
$ tar zxvvf hfst???.tar.gz
$ cd hfst???
$ ./configure
$ make
$ make check
$ sudo make install

Assuming everything is in place, update NEWS and ChangeLog with info about the purpose of this release. The NEWS file shall contain human-readable summary of the major changes since last release (if there are no major changes, do not bother yourself with releasing ;-). The ChangeLog is nearly machine-readable file of all changes in all of the files in the source tree. Use scripts like svn2cl to generate the skeleton and sed to change nicknames into realnames and such. Commit these to trunk.

Merge changes to stable tree. This will usually work just nicely since stable releases will not have changes that cause conflicts. If there are changes to API or backwards incompatible changes you should not be making stable release in the first place.

$ svn co https://hfst.svn.sourceforge.net/svnroot/hfst/releases/stable-x.y \
old-stable
$ cd old-stable
$ svn merge https://hfst.svn.sourceforge.net/svnroot/hfst/trunk/hfst???
[double-check that everything merged nicely]
[assuming it didn't, revert and do a step-by-step svn merge -c]
$ svn commit

Copy the distribution tarball to sourceforge's file release system and tag the version trees:

$ make dist
$ scp hfst???.tar.gz \
username,hfst@frs.sourceforge.net:/home/frs/project/h/hf/hfst/hfst/
$ svn cp https://svn.hfst.sourceforge.net/svnroot/hfst/trunk/hfst??? \
https://svn.hfst.sourceforge.net/svnroot/hfst/tags/release???

Release is done. Now you can play games with sourceforge's web-based admin tools to tweak the details.

Library specific practices

Libraries are used by internal and external projects altogether, so there are many requirements to them. API stability is one of them; public symbols may not be deleted or modified between releases, it is legal to add new ones though. The libraries are versioned by releases, following library versioning standards, not the release numbers; HFST3 has version vector 1.x.y. Libraries do not print unless asked, error handling is done by exceptions in C++ or return values in C.

Tool specific practices

All command line tools follow same argument processing logic, implemented in getopt_long. The non-interactive tools by default print only warnings and errors, but user may specify more verbose or quiet processing. Quiet processing mode must not print anything else than fatal errors. If stdout is not reserved for piped output, messages and warnings are printed to stdout, otherwise stderr. Stderr is always used for error messages.

The typical command line tool works like this:

  1. hfst_set_program_name(char*, char*, char*)
  2. getopt loop (more or less standard, use inc/)
  3. verify option sanity (enough input files, files readable, writable)
  4. open inputs
  5. process inputs, write outputs
  6. clean up and die

To write output to users:

Topic revision: r11 - 2012-02-13 - TommiPirinen
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback