Git Workflow¶

To contribute to the FLARE source code, please follow the guidelines in this section. If any of the git commands are unfamiliar, check out Chapters 3-5 of the Pro Git book.

General workflow¶

Development should follow this pattern:

Create an issue on Github describing what you want to contribute.
Create a topic branch addressing the issue. (See the sections below on how to push branches directly or from a forked repository.)
Merge with the development branch when finished and close the issue.

Master, development, and topic branches¶

The FLARE repository has a three-tiered structure: there is the master branch, which is only for battle-tested code that is both documented and unit tested; the development branch, which is used to push new features; and topic branches, which focus on specific issues and are deleted once the issue is addressed.

You can create local copies of branches from the remote repository as follows:

$ git checkout -b <local branch name> origin/<remote branch name>

Pushing changes to the MIR repo directly¶

If you have write access to the MIR version of FLARE, you can make edits directly to the source code. Here are the steps you should follow:

Go into the development branch.
Create a new topic branch with a name describing what you’re up to:
```
$ git checkout -b <feature branch name>
```
Commit your changes periodically, and when you’re done working, push the branch upstream:
```
$ git push -u origin <feature branch name>
```
Create a Pull Request that gives a helpful description of what you’ve done. You can now merge and delete the branch.

Pushing changes from a forked repo¶

Fork the FLARE repository.
Set FLARE as an upstream remote:
```
$ git remote add upstream https://github.com/mir-group/flare
```
Before branching off, make sure that your forked copy of the master branch is up to date:
```
$ git fetch upstream
$ git merge upstream/master
```
If for some reason there were changes made on the master branch of your forked repo, you can always force a reset:
```
$ git reset --hard upstream/master
```
Create a new branch with a name that describes the specific feature you want to work on:
```
$ git checkout -b <feature branch name>
```
While you’re working, commit your changes periodically, and when you’re done, commit a final time and then push up the branch:
```
$ git push -u origin <feature branch name>
```
When you go to Github, you’ll now see an option to open a Pull Request for the topic branch you just pushed. Write a helpful description of the changes you made, and then create the Pull Request.