HaikuPorts Development Model

This article is dedicated for users with little knowledge on how to use git. If you're an advanced git user, all you need to know is that we prefer getting collaborations as pull requests and the best method to use is to develop in feature-branches. The following part of this article explains this concept.

For this article, we assume the user:

• has cloned and installed haikuporter
• has an account at GitHub
• has forked the HaikuPorts repository
• has cloned their forked GitHub repo

What are feature-branches?

The default branch git creates for you is called master. Typically all your development happens there. However, this is not the best approach because e.g. if you're developing a new feature, you can't fix bugs in an already released version. That's where feature-branches come in. You create a branch called new-feature off of your master. Then if you want to fix bugs without pulling in code of the new, not ready feature, you can just switch the branch you are working on.

We can consider new recipes or updates to existing ones features.

The important part is that you never make changes to your master branch, you only update it. This way you can work on multiple features at the same time, without waiting for your pull request to get accepted. Even if there are any issues with it, you can fix them without messing with other features you are working on.

How do I use feature-branches?

1. Make sure you are on master branch and it's up-to-date.
2. Create a new branch with git checkout -b new-feature. Now you are on new-feature branch.
3. Make your changes and commit them as you'd normally do.
4. Push your changes with git push origin new-feature. This assumes that origin is your fork, not original haikuports repo.

You can change branches with git checkout branch-name. Delete branches with git branch -d branch-name. Note -d is safe - it will delete the branch only if it has been merged. If you want to scrap your work without merging it, use -D instead.

How do I create a pull request (PR)?

To contribute the changes you pushed to your fork to the official haikuports repo, you should file a pull request from the GitHub webpage of your fork.

On Commits page you will see the pushed changes in their branches. Under Actions find the item Create pull request. Here you can select the branch that will be used to create the PR and add a title and description for it.

How do I sync my master branch with original repository?

Note! Do not use GitHub's Compare button.

1. Add the original HaikuPorts repo with git remote add upstream https://github.com/haikuports/haikuports.git.
2. On the master branch: git pull upstream master.

Note! upstream is just an example. You can use any other name.

What to do if my feature-branch becomes outdated?

1. Make sure your master branch is up-to-date.
2. Change your working branch to the branch you want to update.
3. git rebase master
4. If there are conflicts, solve them, add your changes and type git rebase --continue.

Don't merge changes from master using merge command because it will create merge commit, and we don't like them ;). rebase also lets you to change commits in your history but that is beyond the scope of this tutorial.

How do I make one final commit from many for the pull request (PR)?

There may be additional changes that need to made after you create your PR, based on the comments, and in such times the PR may span multiple unwanted commits.

Let us go through the situations and options one by one:

1. I made the PR with one commit, now I need to modify it according to the comments.

   • When you're done with the modifications, you git add path/to/file/you/modified. After that, instead of running git commit, run git commit --amend. This adds your changes to the previous commit. To push that, you will need to specify '-f/--force' option for git push, since you modified the original commit you pushed.

2. I already have multiple commits, and would like to turn them into one. There are multiple ways to achieve this. It is assumed that you have ran git rebase before getting to this.

   1. Run git reset master followed by a git commit, to get all your changes and type a fresh commit message.

   2. If you want to preserve the commit messages of all the commits for some reason, you can use git reset --hard master, followed by a git merge --squash HEAD@{1}, and then a git commit finally.

   3. Something more complex is git rebase -i master, which starts an interactive rebase. You can specify what exactly would you like to do with each commit of yours. Typical usecase for a haikuports PR might be: git rebase -i master, keep the first commit as is

      • Mark the rest as fixups by replacing the 'pick' in front of them with 'fixup' or 'f'
      • Mark the rest as squashes by replacing the 'pick' in front of them with 'squash' or 's'

Useful links

• Rebasing
• Rewriting history
• Remotes