How can I contribute code to Archi?

So you'd like to add a patch or a feature to Archi. How should you do it?

Things to consider

If your planned contribution is to provide new functionality please present it first by opening a new Issue. This way we can discuss how, or if, it will fit into the roadmap. It may be that the feature will fit into another proposal or it is dependent on something else.

Contribution Overview

For all practical purposes, the Archi project follows standard github procedures. To contribute code, you would usually perform the following steps.

1. Fork the Archi project (*)
2. Clone your new fork to your own PC & configure a remote (*)
3. Create a feature branch
4. Make the changes to the code/docs you wish to make (compile, test as needed).
5. Commit the changes to your local clone
6. Push the changes to your forked repository on GitHub
7. Create a pull request for the feature branch

The steps marked with (*) are typically only done once, whereas you do the other steps for each featurebranch.

When your pull request is closed (accepted or discarded), remember to clean up your branches in your own repo, and checkout the main branch: "develop".

For details about the steps, see Forking and Cloning - GitHub Help and Using Pull Requests - GitHub Help.

Example session

This section documents example for console users, that assumes a GitHub username of "username", and that the fork has been performed from the Archi repo:

Initial setup/clone, after forking:

$ git clone https://github.com/username/archi.git
# Clones your fork of the repository into the current directory, placing the clone in directory "archi"
$ cd archi
$ git remote add upstream https://github.com/Phillipus/archi.git
# Changes directory to the fresh clone and configure an upstream remote repository, that can be convenient

Creating the feature branch "myfeature", revising code, commiting, pushing

$ git fetch upstream
# Pulls in changes not present in your local repository. (This is not needed after a clone, but is good habit for later.)
# Retrieves the code
$ git checkout -b myfeature
# Create and checkout a new branch called "myfeature"
# Now, do all your changes and tests....
# ... (change ... test ... change ... test)
# When satisfied, commit to your local repo and push
$ git commit -a
# Commits all changes to your local repo, into the branch "myfeature"
$ git push origin myfeature
# Pushes the changes from your local repo, branch "myfeature" too your forked repo, branch myfeature

After you have pushed your changes to your forked repo on github, visit Archi at GitHub and create a pull request from your recently pushed branch.

Please try to describe in as much detail as possible what the Pull Request is for - does it fix a bug? Does it fulfil a feature request?

Cleaning up

When the request is closed, you can delete the feature branch on github and in your local repo. On github this is done as part of closing the pull request. In your local repo, you do something like this:

$ git -D myfeature
# Force a delete of the branch myfeature
$ git checkout master
# Moves you back to the master branch

Additional Notes

Here's some addtional points in no particular order. Please contribute to this page with your experiences and guidance. We can then tidy it up later.

• The default branch for Archi is the "master" branch. We use a partial implementation of the "Git Flow" method, using feature and release branches. Please see A successful Git branching model for an explanation of the Git Flow methodology
• Git commit messages should be short and to the point. See A Note About Git Commit Messages and search on Google for best practice. We can't always get this 100% right, but we can try.