The following is a quickstart guide to making changes to the  source code and contributing them back to the project. Note that the preferred method to do this is through GitHub.

It's easy to begin working with and changing the  source code. Assuming you have Git (git) installed, just do:

git clone https://github.com/galacticusorg/galacticus.git

and you have a cloned copy of the  repository in the galacticus directory.

If you plan to contribute changes back to the Galacticus project (please do!), you should consider using GitHub. After you've created an account for yourself at GitHub, you can "fork" the repository to have your own working copy. This can be done as follows:

• visit the  repository on GitHub at https://github.com/galacticusorg/galacticus;

• click on the “Fork” button;

• you may need to select which account to fork under (if you have multiple GitHub accounts);

• after the fork completes, you’ll be taken to the overview page for your forked repository.

You'll now want to clone this forked repository to your local system. Click on the "Code" button and copy the URL presented there (you want the SSH version so that you can push changes back to this repository). Run git clone followed by this URL on your local system to get a cloned copy of your new repository. You can now work with this repository, make any changes, and commit then. We’ll discuss how to send these changes back to GitHub, and back to the  project below.

If you want to make some relatively minor changes to the  code, such as fixing a typo, adding a new filter, etc. you can just make changes directly on the master branch (i.e. at the point of active development). To do this, make sure you’re at master:

git pull
git checkout master

Then make your changes, add new files, etc. Once you’re done, first check if there have been any changes to master since you pulled:

git remote update && git status

If any new changes are shown, us git pull to merge these in to your working copy. Then add and commit your changes:

git add <file1> <file2> .....
git commit

Your changes are now committed to your cloned repository.

Once you’ve committed your changes, you can contribute them back to the  project.

If you just cloned the  repository directly you can send a patch containing your changes by e-mail to [email protected]. First, create the patch file using:

git format-patch master --stdout > new-feature.patch

Then simply attached the new-feature.patch file to an e-mail. It will be merged into the  project using

cat new-feature.patch | git am

If you forked the  repository on GitHub, you can now push your changes back to GitHub using

git push

If you want to contribute these changes back to the  project the best way to do so is to create a “pull request”. Simply visit your forked respository on GitHub and, from the “Branch” menu, click the “Pull request” button. On the “Compare” page, click “compare across forks”. In the “base branch” drop-down menu, select the branch of the  repository you’d like to merge changes into. In the “head fork” drop-down menu, select your fork, then use the “compare branch” drop-down menu to select the branch you made your changes in. Add a title and description for your pull request. Finally, click the “Create Pull Request” button. Assuming your code looks good and works, it can then be pulled into the  project.

For bigger changes, particularly those where you're adding a new feature, we recommend using Git's "branch" functionality. Using branches is straightforward. Begin with master and create a new branch:

git checkout -b myNewFeature

where myNewFeature is a name for your branch. Then begin working, make changes, add new files etc. You can make commits when necessary (and it's good to make several small commits rather than one big one). You should merge master into your branch as often as possible to avoid them getting out of sync (which makes for difficulty later when you want to merge your feature branch back into master):

git merge master
git commit -m "merged master into myFeatureBranch"

Once the new branch is stable, you can merge it back into master:

git checkout master
git merge myFeatureBranch
git commit -m "merged myFeatureBranch"

Note that you can always go back and work on a branch later. Just do:

git checkout myFeatureBranch
git merge master
git commit -m "merged default into myFeatureBranch"

then continue to work with your branch as normal.

The Galacticus project follows "Conventional Commits" guidelines for commit messages. You don't need to do this unless you're committing directly to the repo (as opposed to submitting a pull request), but following these guidelines is good practice anyway.