If you are interested in helping OpenDocMan grow, and you have some development or design skills, this document will explain the developer resources.[—ATOC—]
[—TAG:h2—]
Contributing Documentation
OpenDocMan provides a Wiki that contains most of the current documentation including installation instructions, developer references, and how-to’s. Users are encouraged to add or modify the wiki. If you need help using the wiki there are many video tutorials you can watch.
Developer Communications
We have an OpenDocMan developer mailing list which you can subscribed to, and it will be important if you are developing for OpenDocMan.
Feature Requests
Our development process uses a “vote” system to ensure that the most important issues and features are handled as priority. If you would like to vote on, or add a new feature request please visit our UserVoice page. We also provide an area on our side-bar that links to the system. Before you add a new item please search to make sure the feature is not already in the queue.
How To Contribute Your Source Code
Scenario: you want to add a certain feature to OpenDocMan and you can write it, but you do not have write access to the source code repository. Git is designed to make it easy to contribute your code to the project and GitHub is designed to make it easy for the project lead to integrate those contributions.
This tutorial assumes that you already have a working knowledge of git and GitHub.
Short Version:
- Create a new issue at our github page: https://github.com/opendocman/opendocman
- Fork the main repository at our github page
- Clone your new repo onto your local machine
- Create a development branch
- Make your changes, then commit to your local branch
- Push your changes to the remote repository
- Open up a pull request at our github page
Long Version:
Step 1: Document – Create an issue on our issue tracker. It is important that your ticket is as descriptive as possible. ‘assign’ the ticket to yourself, indicating that you intend to contribute code. Once this is complete you will want to take note of the ticket number.
Step 2: Fork – Fork the project to your own GitHub account (I am assuming you already have an account). This only needs to be done ONCE. You’re really not going to use your own fork, but it is important that you have this connection to the main project. You can accomplish this by going to the project’s GitHub page at https://github.com/opendocman/opendocman and clicking the ‘fork’ button in the upper right corner of the page. After a few seconds, your fork will appear in your own account.
Step 3: Clone – Clone the project to your local machine (NOT your fork!). This is also only done ONCE per project.
[box type=”note”]$ git clone git://github.com/opendocman/opendocman.git my.opendocman.fork[/box]
This is telling your local git installation to create a repository with the source from git://github.com/opendocman/opendocan.git and give it a name called my.opendocman.fork (you can choose a different name if you wish). Remember that the repository is created in the directory you are performing the command.
Step 4: Add a Remote – In order to push your changes somewhere where they can be found and pulled into the project, you need a new remote. This is because we cloned the main project and we don’t have ‘push’ rights to that project (origin). A remote is a pointer toward an online repository (source). Go to your own fork of the project at GitHub and copy the SSH link for the project. It should look something like this: [email protected]:opendocman/opendocman.git. Then do the following:
[box type=”note”]$ cd my.opendocman.fork
$ git remote add my.opendocman.fork [email protected]:yourname/opendocman.git
$ git remote [/box]
you should have a list of two two remotes: ‘my.opendocman.fork’ (the pointer to your own forked repo at GitHub) and ‘origin’ (the pointer to the original project repo at GitHub).
Step 5: Branch – You should create a branch of your repository in which to make your changes. This is where you would need the ticket number you noted earlier (I’ll use Ticket #1234).
[box type=note]$ git branch Ticket_1234
$ git checkout Ticket_1234[/box]
Step 6: Code & Test – Now you can code all you like. All your changes are taking place in the Ticket_1234 branch and the master branch remains unchanged. You can use your favorite IDE in order to do your development. I recommend NetBeans but others use Eclipse or Aptana or others. Be sure to test all your changes and make sure you follow appropriate QA procedures for the project.
Step 7: Commit – This can actually be done multiple times if needed. When you have finished your coding for all or a part of your additions, commit your changes to your repository. Be sure your commit messages references the appropriate ticket number. (Commits can be done several ways. Therefore there is no example here).
Step 8: Rebase – Since the main project may have changed since you pulled your source. It is important that you ‘rebase’ your source code. This will bring your code up to date and alert you to any conflicts that may have occurred between your code and the changes that may have been made.
[box type=note]
(make sure you are in the correct branch)
$ git checkout Ticket_1234
$ git pull –rebase origin[/box]
If there are any conflicts, you will be notified. Resolving those conflicts is outside the scope of this tutorial. If this occurs, you will need to resolve all conflicts before continuing.
Step 9: Push – You now need to push your changes to a remote branch at your fork at GitHub so that they can be reviewed and possibly incorporated into the main project
[box type=note]$ git push my.opendocman.fork Ticket_1234[/box]
Step 10: Issue Pull Request – In your browser, navigate to your fork at GitHub and select the branch you want to ‘send’ to the project lead. Click the ‘Pull Request’ button in the upper right corner of the page. Describe your request and submit the form.
Step 11: Keep Up To Date – It is helpful to the project lead if you keep your ticket branch updated to the latest commits. This makes your branch easier to integrate when the project lead gets to it. Since this could be days or weeks, other commits to the main project may occur in between. To do so, simple rebase your local branch (step 8) and push the changes to your branch (step 9). This will keep your branch up to date.
