How To Contribute

How to contribute

Basic Workflow of Github

It's very cool to use Git and Github as the collaborate tools for JdeRobot development.

The basic workflow would be like:

• Fork the JdeRobot repository
• Clone your own JdeRobot repository using Git
• Create a new branch for new features and bug fixes
• Work on your branch and get it run and tested
• Commit your changes and open a pull request
• Make changes regarding the discussions of your pull request

For now, I'm gonna demo this workflow using my Github account and try to add a dummy feature, since the contribution process is not so well documented, I will start here to add a section named How To Contribute to the README.md file of the project. Here we go!!!

Fork the JdeRobot repository

First of all, to make your changes accepted as a contributor, we have to Fork the repository. For more roles of a Github project, see here.

To fork a repository on Github, just click on the right corner of the project page as illustrated below:

Then follow the panel to choose where your fork should go, typically you will select your personal Github account if you got many choices, for me I choose(@hustcalm) as:

After that, you should be redirected to the new repository under your account, for me, it looks like:

Clone your own JdeRobot repository using Git

Once you have forked the repository, it's time to start some hacks on your repository! However, first of all, you have to clone the source code using Git:

Basically, you have 3 options:

• HTTPS
• SSH
• Subversion

No big differences, just different protocols. If you have set up your Github SSH, I suggest using SSH. For using HTTPS, you will be prompted to input user name and password when accessing your Github repository from terminal.

Now, open your terminal and cd to a proper directory, then clone:

Create a new branch for new features and bug fixes

For contribution, developers will always add new features or fix bugs. For easy development management, we will use branches. For default branches after a fresh clone, you can see them by git branch -a:

To create a new branch, use git branch branch_name, this will create a new branch based on your current working branch. Like git branch JdeRobot_how_to_contribute:

Switch to the new branch using git checkout branch_name, this will make branch_name the current working branch. Like git checkout JdeRobot_how_to_contribute:

OK, let's have a check to just make sure, you can always run git status or git remote to see what is going on with your local repository:

For more useful commands about Git, you can always run git help.

Work on your branch and get it run and tested

Well, really time to hack! Now you can concentrate on your new feature or bug fix and show your talent:-)

As for the demo, I will edit the README.md file, like:

The edited file would be like:

After your hack, make sure your changes are doing well, especially not destroying the compiled source code. Tests are great ways to make things right, so please test your changes and make sure everything is just fine!

Commit your changes and open a pull request

Once you are done with your feature or bug fix, time to share with the community:-)

Basically, you should:

Commit your changes

Push to your repository

Create a pull request

To create a good pull request, be sure to make things clear:

Make changes regarding the discussions of your pull request

Coding Style

We use doxygen as code documentation system, so we can easily generate an online version of the API documentation. Adding doxygen comments to your code is as easy as adding regular comments, you just have to follow some rules and learn a small set of tags. You can find a complete manual here.

This is a documented code snippet with some examples of doxygen documentation:

/**
 *  A test class. A more elaborate class description.
 */

class Test
{
  public:

    /** 
     * An enum.
     * More detailed enum description.
     */

    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Test();

      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;
   
      /** 
       * a public variable.
       * Details.
       */
       int publicVar;
       
      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

And here you can see the html generated documentation.