How can I contribute code to Archi?

So you'd like to add a feature or bug fix to Archi

Do not just submit code or a Pull Request without prior agreement. It will be rejected.

Before submitting a Pull Request

If your planned contribution is to provide a new feature please present it 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 is dependent on some other feature or fix.

If you submit a Pull Request without prior discussion it will be rejected.

Contribution Overview

If it is agreed to proceed and you then create a Pull Request please choose the "Draft" option. It can be converted to a normal Pull Request later after agreement and review

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 Draft Pull Request for the feature branch

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

For details about the steps, see Forking and Cloning - GitHub Help and About 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 Draft Pull Request from your recently pushed branch.

Please try to describe in as much detail as possible what the Draft 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 additional 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.