Skip to content

NewDeveloper

Jump to bottom Edit New page
tkren edited this page Feb 13, 2013 · 5 revisions

Table of Contents

New developer information

Follow the next steps if you want to help developing DLVHEX and its plugins.

  1. Create a Sourceforge account: http://sourceforge.net/account/registration/
  2. Send an email with your Sourceforge UNIX name to the project admins: [email protected], [email protected], [email protected], [email protected] (see also the member list)
  3. Subscribe to the following mailing lists:
  4. Checkout the source code: 
svn checkout --username YOUR-SF-NAME https://dlvhex.svn.sourceforge.net/svnroot/dlvhex dlvhex-svn
  1. Get familiar with the Boost libraries
Now you are ready to compile and commit your changes. Here are some tips and tricks for svn: http://gcc.gnu.org/wiki/SvnTricks. If you are working in a branch, please consult http://gcc.gnu.org/wiki/SvnBranch for a quick tour through the most important commands.

Get used to C++

Put this book on your bedside table: The C++ Programming Language.

Here are some nice references and manuals that cover many aspects of C++:

The CxxDebuggingTutorial shows how to debug C/C++ programs.

Commit EARLY and commit OFTEN

We have put this item close to top here because it is very important: please commit early and often. As software development is an evolutionary process, it is better to do changes gradually, instead of committing now and then. What's more, having small changesets means that you can easily jump between revisions, and you can simplify the merging of branches and trunk. Don't be shy: do not hesitate to commit your code because you think it is not clean and some parts are stupid and you want to rewrite it first. There ain't no such thing as stupid code (TANSTASC). There is only pain when you want to merge code between branches. There is only pain when you have realized that you had a thinko and developed in the wrong direction for some time (we can only help you early if you commit early). The only stupid code is non-existing code. A good rule of thumb is to commit at least daily when you are in devel mode. If the commit intervals are longer, there is something wrong.

Every commit triggers an email to the DLVHEX notification mailing list, so please subscribe here to follow the development in real-time.

Contribute back to the community

It is very likely that you will find bugs in (i) DLVHEX, or to a lesser extent (ii) in some libraries/programs that we are using. In case of (i), please (really!) write a bug report (I mean it): see the section below. Regarding (ii), never hesitate to send the project team bug reports, here is how and why: Curing Shy-Developer-Syndrome. This goes in line with Shy-Committing-Syndrome described above. If you find a missing feature in some library, maybe it's time to roll up one's sleeves and send them a patch.

Please discuss problems and ideas here: dlvhex-devel mailing list. Subscribe here also for general discussions and support.

The DLVHEX Trac

Report bugs using the ticketing system. Please check bug reports (see also the note on ChangeLog and commit messages below).

You can view the list of changesets and closed bugs at the timeline. The source code browser is also handy.

Create milestones for long-term goals.

A tour through the repository

The DLVHEX repository is located at https://dlvhex.svn.sourceforge.net/svnroot/dlvhex/. Therein, you can find several subdirectories (we adhere to TTB-style repository layout):

  • dlvhex: the DLVHEX core
    • trunk: main development
    • branches: some DLVHEX branches
    • tags: release tags
The plugins are located in their own subdirectories:
  • dlvhex-XYZplugin: the XYZ DLVHEX plugin
    • trunk: main development
    • branches: some XYZ branches
    • tags: release tags
Huge plugin frameworks may have their own directory structure:
  • dlvhex-ABC: the ABC DLVHEX plugin framework
    • dlvhex-FOOplugin
      • trunk: main development
      • branches: some FOO branches
      • tags: release tags
    • dlvhex-BARplugin
      • trunk: main development
      • branches: some BAR branches
      • tags: release tags
      • ...

Documenting your package

We follow the autotools way to package documentation, i.e., we need the following files in the top-level directory of each package:

Documenting your source code

Let me give you an analogy: imagine you have a child, you raised it, helped her through school, see her flourish. You cut back on your own little hobbies. And then, when she has reached adulthood, you abandon her out of the blue and never see her again.

THIS IS WHAT YOU WERE DOING IF YOU WOULD REFUSE TO DOCUMENT YOUR SOURCE CODE! ARE YOU REALLY THAT HEARTLESS AND CRUEL?

It should be a matter close to your heart to document your source code. Undocumented functions, classes, member variables, algorithms, ... are UTTERLY USELESS. PERIOD. NO EXCEPTION. Is it really that hard to spend 2 minutes after you have typed in the code (presumably for hours or even days), and add a few lines of information? It takes aeons to understand undocumented foreign code. What's more, after a couple of weeks, you yourself won't understand what kind of strange design decisions you took during the development ;-). In the end, no-one understands what is going on and all what is left is to rewrite everything again when a new version of whatever is out. So please, I beg you imploringly, add a bit of information, just a couple of lines that steps the reader through the bulk of code and explain what is going on. Give every class/file/function/member a brief description that explains what it is roughly doing. Give every complicated block in an algorithm a brief description that explains what it is roughly doing. It is not that hard.

Use doxygen to generate various formats of the documentation, it helps you and us to keep track. If you are a member of the Church of Emacs, have a look at doxymacs.

Thank you.

PS: This is also a small code-comment HOWTO :D

Commit messages

When you commit changes to the repository, use the entries in ChangeLog as commit message. When you close a bug ticket, append 

(Fixes #NNN)
to the commit message to indicate that you have fixed ticket #NNN from the bug database (the trac system will then automagically recognize it for closing the bug in the system). When you commit something that references a previous commit like "Fixing faulty revision r12345," always put an "r" in front of the revision: Trac will then automatically create a link to this changeset in the timeline.

(Emacs automates the process of maintaining ChangeLog: just hit C-x 4 a inside the changed file or inside the svn-diff output buffer, and you will get a new entry. When you commit using psvn.el, hit C-c-a in the commit message buffer and you will get the right change messages from the ChangeLog.)

Undoing a faulty commit

Say you commit something by accident which does not make sense in r12345. First make sure that your code is up-to-date: 

svn update
Then, you can easily go back in time using svn merge: 
svn merge -c -12345
followed by a new commit 
svn commit -m "Undo r12345."

If the commit comprises of multiple files, but you only want to undo particular files, just invoke 

svn merge -c -12345 file1 file2 ...
and 
svn commit -m "Undo r12345." file1 file2 ...

Merging between trunk and branches

A quick guide can be found here: http://gcc.gnu.org/wiki/SvnBranch and http://gcc.gnu.org/wiki/SvnMerge

Never forget to run 

svn update
before the merge. Merging from trunk or from branches should not require a ChangeLog entry. However, when you merge something into a branch or back to trunk, use 
Merge rXXXX through rYYYY into branch ZZZ.
resp. Merge rXXXX through rYYYY into trunk. </pre> as commit message (<tt>rXXXX and rYYYY stems from the output of svn merge).

Writing and working with a testsuite

Every plugin must have a testsuite that can be run with make check. We use automake's test suite facility: see http://www.gnu.org/software/automake/manual/automake.html#Tests and http://sourceware.org/autobook/autobook/autobook_98.html. It is best to have two types of tests: unit tests (test your components and classes) and program tests (a shell script calls dlvhex with your plugin and the generated answer sets must be compared with some reference file).

Unit test frameworks like http://www.boost.org/doc/libs/release/libs/test/ greatly simplify the generation of a test suite. We also have some python scripts that can run dlvhex, collect answer sets, and compare them with some reference answer sets.

We have agreed upon the following directory layout for testsuites. The unit tests and shell scripts for running tests should be put into the top-level testsuite directory. If a testsuite is using example programs to verify the correct behavior, they should be put into examples, as they are interesting on their own and already document how to use your plugin. This means that the code in testsuite must refer to examples for the files.

Assert EARLY and assert OFTEN

Check Tony Hoare's slides Assert early and assert often, 'nuff said.

Nightly builds

http://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Full_Moon_Luc_Viatour.jpg/119px-Full_Moon_Luc_Viatour.jpg

We have a local Linux box running a buildbot farm which creates nightly builds at 3:30 A.M. (using various configurations of compilers like gcc {4.3,4.4,4.5,4.6} and clang trunk, and the mighty boost >= 1.42 plus boost trunk) of the dlvhex + plugins trunks and branches. The whole build cycle roughly takes 1 hour. It runs all tests using make check, and creates tarballs of them (make distcheck). The nightly build logs will be sent out to to the dlvhex-nightlies mailing list: just subscribe to get nightly build logs.

The buildbot configuration is available are here: https://sourceforge.net/apps/trac/dlvhex/browser/dlvhex-buildbot/. You can check the detailed build reports and logs here (internal access only): http://gluck:8013/waterfall

If you want your plugin to be included in the nightly build cycles, please drop us ([email protected], [email protected], [email protected]) an email.

Creating a release

Invoking 

make distcheck
creates a tarball PACKAGE-VERSION.tar.gz of your package. We have a synchronized release policy: dlvhex + plugins will be released in one go. On the release day, each package trunk will be tagged with the release version: 
svn copy https://dlvhex.svn.sourceforge.net/svnroot/dlvhex/dlvhex-XYZplugin/trunk https://dlvhex.svn.sourceforge.net/svnroot/dlvhex/dlvhex-XYZplugin/tags/Release_A_B_C

Every fresh release will be announced here: dlvhex-announce mailing list.

Add a custom footer
Add a custom sidebar
Clone this wiki locally