Submitting new or updated packages

The following directions can be followed to submit new packages or updates to existing packages.

Currently (Jan 14, 2018), only core members have direct commit access to the fink-distributions git repository. This may change in the future. For now, updates should be done via pull requests in GitHub. Pull requests happen from a branch of your fork of the fink-distributions repository.

All these commands are doable from the command line. They can also be done via a GUI app like SourceTree or GitHub Desktop. Most steps listed will below will be exampled for the CLI, but can be done in the GUI software.

Setup SourceTree

In the Preferences menu, under "Git", make sure that the option "Use rebase instead of merge by default for tracked branches" is checked. This helps generate cleaner commit logs.

Fork the fink-distributions repository and clone it to your local computer

1. Fork https://github.com/fink/fink-distributions/ to your GitHub account
2. Clone your fork to your computer
3. Configure the fork so that it knows about the upstream original

• https://help.github.com/articles/configuring-a-remote-for-a-fork/

4. Update your fork to keep up with the latest releases in the master git repository

• https://help.github.com/articles/syncing-a-fork/
• For the last step, I use git rebase upstream/master instead to avoid merge commits.

Your fork is now ready to make changes to.

Your first commit

Pull requests work best when you do them in branches. Keep branches specific to a topic, such as 'new version of libFOO', or 'add py37 variants'.

1. Make a branch for your update(s) and switch to it

• git checkout -b <BRANCHNAME>

2. Edit your files and save them
3. Commit your changes to your local copy of the fork. Give a relevant and descriptive message

• Best done in a GUI until you're more comfortable with git

4. Repeat steps 2 and 3 as necessary
5. If you wish to simplify the commit history, you can squash commits together into a single one.

• In SourceTree, select the commit before the earliest one you want to squish. Right-click and select Rebase children of XXXXXXXX interactively. Don't forget to edit the commit message of the resulting squished commit.
• Do not edit/squash/modify commits once you've pushed them from your local checkout to the remote (on Github) fork. Editing a public commit history is difficult to deal with.

Create a pull request

1. Push your branch to the remote copy (origin) of your clone. Remember that once you push to remote, it's a lot harder to undo things.
2. In GitHub, create a pull request of your branch against fink/fink-distributions:master.
3. The pull request will then be reviewed and merged if it's OK.
4. If any changes need to be done, go back to your local copy of the fork, edit files and commit changes, and then push them. The new commits will automatically show up in the pull request.
5. Once the pull request is accepted and merged, then you can delete the branch (both local and remote copies) from your fork (easiest done in Sourcetree by right-clicking on the branch name and selecting the Delete option. You will need to not have that branch checked out).

Keeping your fork up to date

You'll need to keep your fork updated so that you can catch updates done by others.

git checkout master
git fetch upstream
git rebase upstream/master

If you have uncommitted changes in your repository, the rebase step might give an error. In that case, either commit or stash (stash works great for works in progress), then git rebase upstream/master again. To recover your stashed changes, use git stash pop.

After rebasing, your local copy of your fork will be ahead the remote fork. Use git push origin/master to keep them in sync.

To submit a new change set, make sure your local copy of the master branch is up to date (see above), make a new branch, and repeat the above steps as necessary.