OpenCog

Notes taken from the opencog/HACKING file. See also: BuildingOpenCog and Branches.

The OpenCog source code repository has moved from Launchpad (Bazaar) to Github, with a mirror on Launchpad.

Coding standards

Whitespace

Required for code consistency and patch acceptance:

• use 4 spaces for indentation
• never use tabs, only spaces (for instance 8 spaces instead of 2 tabs)
• use 80 columns max
• use unix-style end-of-lines (all decent win32 editors support it)
• use definition-block brackets on a new line and command-block brackets on the same line
• use spaces between expression operators ("i + 1" instead of "i+1")

Includes

When including source files from within OpenCog, you should use the following examples as a guide:

// For headers within the same directory:
#include "myheader.h" 
// For headers within a sub directory of the current:
#include "subdir/myheader.h"
// For headers in a parent directory, you should
// use the full opencog include path, and ensure that path
// is in the CMakeList.txt include directive...
#include <opencog/util/RandGen.h>

Documentation

We use Doxygen for generating code documentation.

This allows a variety of markup to be used, and developers of OpenCog should become familiar with the basic markup and types of comment available. Remember, the time spent on in depth documentation pays itself back multiple-folds when it comes to others (and yourself!) revisiting code you wrote a year earlier.

The basic way of documenting a function would be:

/** Brief description of foo.
 * 
 * An optional and more in depth description of foo
 *
 * @param bar A description of the bar parameter.
 * @param bar2 A description of the bar2 parameter.
 * @return A description of the return value.
 *
 * @bug A bug with foo (should really be in the Github issue tracker!)
 * @todo something missing from the implementation of foo (this gets
 *       added to a global todo list, very handy)
 */
int foo(string bar, bool bar2);

As you can see, we use the @ prefix for special commands.

For a full description of the commands available see the list of special commands. There are also various tutorials to be found on Google.

Checking with astyle

To check whether your code complies with our standard, you may use the tool "astyle". Make sure you use the following options:

prompt-$ astyle --indent=spaces=4 --brackets=linux --indent-labels \
          --pad=oper --one-line=keep-statements --convert-tabs \
          --indent-preprocessor file.cc
prompt-$ diff file.cc file.cc.orig

Vim

If you use the VIM editor, you may add the following line to your ".vimrc" configuration file to automatically setup your editor to use opencog's style when editing a source file from OpenCog's tree:

autocmd BufNewFile,BufReadPost * if match(expand("%:p:h"), "/opencog") >= 0 && &filetype == "cpp" | set ts=4 sw=4 tw=80 ff=unix cindent expandtab | endif

Emacs

If you use Emacs, you may add the following lines to your ".emacs" as well:

(setq-default indent-tabs-mode nil) ;; use spaces instead of tab
(setq-default c-basic-offset 4) ;; set c based language indent to 4
;; open cxxtest files in C++ mode
(setq auto-mode-alist (cons '("\\.cxxtest$" . c++-mode) auto-mode-alist))

If you want to use CEDET, here is some help. And if you want to use flymake, now part of emacs, here is some help.

Git HOWTO

1. Browse to https://github.com/opencog/opencog login and click Fork.
2. In a shell:
   1. git clone https://username@github.com/username/opencog
   2. cd opencog
   3. git checkout master
   4. git pull
   5. git branch my-latest-fix
   6. git checkout my-latest-fix
   7. hack hack hack
   8. git commit -a -m "commit message"
   9. git push https://username@github.com/username/opencog my-latest-fix
3. Browse to your personal branch, click Pull Request and wait for your pull request to be reviewed. Optionally:
   1. git checkout master
   2. git branch -d my-latest-fix

Notes (the numbers in the list below correspond to the numbers in the list above)

1. Creating your personal fork, out of which you can manage numerous consecutive and/or parallel personal branches. This is a one-off step.
2. 1. This is also a one-off step.
   3. Implied by the 'git clone' command, if issued
   4. No changes will be pulled if 'git clone' command was just issued.
   5. Creates a new local working branch
   6. Moves to the new branch
   8. Make as many commits as you like before going on to the next step (push).
   9. Push your work to your personal branch on Github
3. 1. If you've finished working with the branch, including making changes suggested in Pull Request comments, optionally delete the local copy, and/or return to step 2.3 or 2.7.

Now, you don't have to delete the branch, or wait for the merge; you can keep on working in that branch, and then issue new Github pull requests for new work. This could become a problem only if one of the series of Github pull request was denied for some reason -- then you've got a bunch of work depending on a patch that is being denied. Thus, if you have several logically unrelated tasks, its best to do each in a separate branch. But, if you have a long series of tasks all working on the same thing, and its all more-or-less your current project, it would be very unlikely that anything would be denied, so just keep working in the same branch, issue Github pull requests every now and then (to get your code upstream), and maybe pull from master every now and then, (if you really need to). And, in the meantime, if you spot some other completely unrelated bug that you want to fix, you can always make a new branch (locally, off of master), fix it, push it, and go back to your usual working branch like nothing happened.

The procedure to bring your local copy of master in sync with the master branch on Gitub is :

1. In a shell cd'd to the root of your local branch:
   1. git remote add upstream https://github.com/opencog/opencog
   2. git fetch upstream -v
   3. git merge upstream/master -v

Dependencies

All OpenCog dependencies are found in the standard Ubuntu software repositories. If you would like to develop new features and are unsure about your choices with respect to new dependencies (libraries, etc.) please discuss on the mailing list. The use of standard packages for dependencies is a great benefit to the ease of setting up new development environments and to the efficiency of deploying OpenCog. Contributions which do not meet these guidelines require special review and may not be accepted into the master mainline branch on Github.

Patches & Merges

Patches should generally follow LKML (Linux Kernel Mailing List) standards and acceptance criteria. Large or significant changes from new developers should be broken into small revisions, uploaded to a user branch on Github and a Pull Request made for discussion. Small patches may be emailed (ask for an email address to send patches at #opencog on IRC.freenode.net).

Please ensure your code conforms to the #Coding Standards.

Help review code changes

The more eyes we have glancing over the commits, the more likely people will conform to code style conventions and more importantly you may catch bugs before they become a problem later!