Development Introduction

Repository Management

Contents

Introduction

Net Responsibility's (NR) main website, www.netresponsibility.com, mainly targets common end users. This means we try to avoid language there that is too geeky and keep things simple. However, our code developers, website designers, and documentation contributors need a place to discuss the technical aspects of the project. The best way to do this is to subscribe to one or both of our development-related mailing lists. Code developers will find it helpful to read the "Getting Started with Coding" guide first. Those interested in contributing to documentation will find it helpful to read the "Documentation" guide first. Those interested in helping out with website design, translation, or other parts of NR development may also find it helpful to browse through the above two documents first for any relevant information.

Mercurial and BitBucket

It's also important that there is a way for multiple people to access and change the NR code, documentation, and similar information, submit their changes, and have those changes tracked and recorded. To meet these needs, we use the Mecurial distributed version control system (DVCS) to manage our code, documentation, and website development, and we host our various repositories (repos) at BitBucket. The NR code repo is found at https://bitbucket.org/netresponsibilityteam/net-responsibility , and the NR documentation repo is found at https://bitbucket.org/netresponsibilityteam/net-responsibility-documentation .

Once the mercurial package is installed, hg provides a command line interface to the Mercurial system. You can use the terminal command info hg to view more info on how to use it. For those interested in a graphical interface, we recommend TortoiseHG. Mercurial also provides good Windows support.

Clone the repository

The first thing you want to do is get a copy on your local system of the repo(s) you are interested in contributing to. To do this you first need to create a BitBucket account if you don't have one, use BitBucket to fork a branch of the repo, and then clone that branch to your local system. The NR code repo contains the bleeding edge code, waiting to be released whenever considered stable enough. The NR documentation repo contains the source files for the current documentation on the NR website, as well as any changes that have been pulled into the repo but not yet uploaded to the website. Here is a sample of the terminal command you would use (from within the desired directory) to clone your new branch to your local system (you will need to replace <path/to/forked/branch> with whatever the path is to your forked branch on BitBucket):

hg clone <path/to/forked/branch>

If you go to the BitBucket page of your new branch, you can also just click on the 'Clone' button and copy the command from the window that opens.

Bug reports and Feature requests

We'll try to keep all bug reports in our issue tracker. If you stumble upon a bug that is not present in the issue tracker, please add it. Regular end users may report bugs and ask for help in the forum, but it's important for us to also have it in the issue tracker, since it will help us know whether it's taken care of or not.

The same thing goes for feature requests. Please help us update both the bug reports and feature requests by adding all relevant entries.

The issue tracker will serve as a kind of TODO list. If you're uncertain where to start with the coding, documentation, or other aspects of the project, start looking through this tracker. If you find a bug or feature request that sounds interesting, get on it. As these entries are taken care of, one may mark them as fixed.

Website Bugs or Feature Requests

If you wish to view bugs or feature requests related to the NR website, you can do this in this section of NR's issue tracker. If you're interested in contributing to the website's development let us know.

Accessing the issue tracker: Security warning, and Login

When you try to access the issue tracker, your browser may display a security warning. You can safely ignore this and grant a permanent security exception. For more info, see this FAQ entry.

Anyone can go to the issue tracker and view the various bug reports, feature requests and other information there. However, in order to create a new issue (bug report, feature request, etc.), you will need to sign in with your NR user login information. The first time you do this, you may need to give some basic additional information in order to gain access. Also, even if you're already logged in to the general NR website itself, you may still need to log in to the issue tracker area of the website.

Submit changes

Here is the preferred workflow for contributing to the NR project:

  1. Use BitBucket to make a fork of the repo you wish to contribute to.
  2. Clone this forked repo to your local system to serve as your local repo. (Note that you can clone more than one branch of the same repo, which may be helpful if you are working with more than one bug or feature at the same time.)
  3. Make whatever changes you want, and commit to your local repo regularly. (During this step, code doesn't have to be able to compile, documentation doesn't have to be perfect, etc. since it is still isolated from the main repo and other developers.)
  4. Push your changes to the forked repo, in preparation for submitting them to the main repo. (At this stage, code should compile locally and have no known bugs, and documentation should be self-checked and/or tested locally as much as possible.)
  5. Use BitBucket to compare your forked repo with the main repo and adjust your forked repo for conflicts, if any.
  6. Use BitBucket to create a pull request from the forked repo (source) to the orginal repo (destination).
  7. If/when a pull request is accepted by the owner of the original repo, the changes in the forked repo will be merged into the main repo. (If you would like to see the effect of your changes being merged into the main repo, you can test this on your own by cloning the main repo to your local system and then merging your local repo into it.)

If you are unfamiliar with Mercurial and new to BitBucket, there may be one or more parts of this workflow that are not clear to you. If you want to find out more about Mercurial this basic tutorial will give you a start. If you haven't used BitBucket before, you will find this guide helpful to get started.

If you are working with bug reports and/or feature requests, please keep the issue tracker (which is interactive with BitBucket) updated with your progress. If no bug report or feature request is found for the specific issue you're working on, please create a new one. This makes it easier to manage the contents of the issue tracker.