CONTRIBUTING.md

Fixed a bug? Implemented a new feature? Want to have it included in QuaZIP? Here's what you need to do.

0. If you don't have a GitHub account, create one. It's ridiculously easy.

1. First, open an issue. Even if you have already fixed it. It helps to track things because instead of a commit saying “fixed this and that” you have a reference to a full issue description.

2. Next, send a pull request. This is sort of counter-intuitive, so if you never did it, read on.

Contribution guidelines

To avoid spending time on something that may never be accepted, here are some guidelines.

1. Changes should be backwards-compatible. Don't just change method names and their signatures randomly. Don't just remove deprecated features—some of them are there to keep compatibility with old Qt versions. Currently supported are versions since 4.6.

2. If your changes aren't limited to a small fix or a convenience method, discussing them in the issue you just opened (if you didn't, do!) could help to achieve some agreement on what exactly is a good idea in your case.

3. Whether you're fixing a bug or adding a new feature, it's an awesome idea to add a new test in the qztest subproject. This way you make sure the bug stays fixed and the feature keeps working.

4. It would be nice if you also update NEWS.txt with whatever changes you propose. Just add another line on top.

5. QuaZIP policies on PR commits are these. Don't squash your commits until the discussion on the PR is over and it's approved. Do squash them, however, once it's approved, unless asked otherwise. And finally: rebase, don't merge. QuaZIP keeps mostly linear history. If you have no idea what it's all about, read on.

How to submit a pull request

What is a PR anyway?

There are numerous sources that describe this already. Ideally, you should familiarize yourself with both GitHub and Git. But you could lack time. Or maybe you don't use Git in your daily work. Or something else. In either case, here are some basics to get you started without spending too much time researching something you might never need again.

Pull requests (PRs) are GitHub's way of sending patches to people. Except that instead of sending a patch, you send a full-fledged version control branch that is much easier to integrate than a regular patch.

The overall process is that you have a full copy of the repository both at your GitHub account and on your computer. You create a new branch on your computer, make some changes, commit to that branch and finally send these commits to your account. Then, GitHub takes over and offers you to create something like a specialized forum topic with your changes attached to it much like a patch would be attached to an e-mail message. Except that it's actually alive—whatever changes you make later on will cause the patch to be automatically updated with all your changes combined.

Setting up for a PR submission

Here are the steps you need to follow if you're sending your first PR to QuaZIP. You don't need to repeat these each time.

0. If you haven't installed Git yet, do so. In Windows, choose the recommended setting for line endings.
1. Go to https://github.com/stachenov/quazip.
2. Click “Fork” in the top-right corner and wait until forking is complete.
3. You should now have a full copy of QuaZIP in your own GitHub account. This may sound like a huge overkill to just send a small patch, but it's actually very convenient once you get used to it.
4. Clone QuaZIP to your computer. Use your own account's repo URL as a source, NOT https://github.com/stachenov/quazip! To do it, run

git clone https://github.com/your-user-name-goes-here/quazip

This command will create a new quazip directory and clone into it. Now you have two QuaZIP repos. One in your GitHub account, accessible to you only via GitHub itself, and another one in the directory that has just been created. Let's call the repo on your PC the local repo. It is rooted at the directory that was created by Git when you ran the above command. Most Git commands from now on should be issued from within this directory unless specified otherwise.

5. Go into the local repo and run

git remote add upstream https://github.com/stachenov/quazip

This commands tells Git that there is another copy of the same project. Now that copy will be accessible by the name “upstream”. You could use any name here, but “upstream” is a common name for such a typical case. Another typical name is “origin”, which was already added by Git when you ran the “clone” command. Now run

git remote -v

This command lists the configured remotes:

origin  https://github.com/your-user-name/quazip (fetch)
origin  https://github.com/your-user-name/quazip (push)
upstream        https://github.com/stachenov/quazip (fetch)
upstream        https://github.com/stachenov/quazip (push)

Every remote is listed twice because there are two operations: you can send (push) commits to a remote repo, or you can receive (fetch/pull) commits from one. Of course, you can't commit to the upstream because you have no write permissions for it, but Git doesn't know about it, so it added both lines for the upstream. Just ignore the push one.

Now your local repo knows how to exchange commits with your GitHub account and with the main QuaZIP repo. You're all set for submitting your first PR.

If you ever wish to submit another PR, no need to do all this again. Except that if you delete your local repo, you'll have to redo steps 4 and 5. But you may need to update your master branch before you start working on another feature for another PR. See “Reintegrating the latest upstream changes” below.

Making changes and submitting a PR

Submitting a PR is easy, but can be confusing first time if you're not familiar with Git.

1. Create a new branch in your local repo. This is very important! Most Git repos, including QuaZIP, have the main branch called “master”. By creating a new branch you tell Git where your changes begin and end. This way GitHub can automatically create a patch containing only your changes. To create a branch, run from your local repo:

git checkout -b new-branch-name

Name the branch whatever you want, it's totally unimportant as it will be deleted later. If you already have some changes in your working dir, but have not added/committed them, it's still not too late to create a new branch, your changes will be kept.

2. Make whatever changes you want.

3. Run git diff to review the changes.

4. Run git add with all changed/added files as arguments. git status will remind you what files you have changed or added. After you're done, git status should show all your files as “changes to be committed”. Note that if you change a file, add it, then change it again, you need to re-run git add or you end up committing your file as it was when you first added it (Git remembers its contents at that time).

5. Run git commit. Enter a meaningful commit message. See Git docs for examples and recommendations.

6. Run git log -p. It shows what changes you made. It's especially useful on Windows where git diff might have shown that everything is fine, but git log -p mysteriously shows that you have changed every single line of a file. It means you have screwed up line endings. Don't worry, you can overwrite your last commit.

Another useful thing to look for is to look for branch names here. Your last commit should have something like HEAD -> my-feature, whereas the previous one should have origin/master. This is exactly the kind of information that will be used by GitHub. Everything that goes after the origin/master commit will be included in the patch you're about to submit.

6. Run

git push -u origin your-branch-name

This weird command sends your committed changes to your GitHub account. The -u option tells Git to remember that your branch goes to your account under the same name so you don't have to type it again.

7. Go to your account's page and open quazip there. You should see a message informing you about the new branch and offering to create a PR. Just do it. Don't be afraid to mess something up as your changes aren't going anywhere yet. If there's something wrong with them, I'll just tell you what and how to fix.

How to fix mistakes

If you have committed your changes, but not yet pushed it, you can always replace the last commit. Just fix your mistakes, git add modified files again and then run

git commit --amend

It will look like a regular commit procedure, except that you're not adding yet another commit to your repo—you're replacing the last one.

If you have already pushed the last commit, it's no big deal either. Except that you need to re-push your amended commit to GitHub, and Git by default will not let you do so. Easy to override, though:

git push --force-with-lease

Squashing commits

You may end up with a pretty messy history with lots of commits. Before submitting a PR, you may wish to tidy up your history a bit. It's beyond this short tutorial to explain how to rewrite history in Git, but the simplest change you can do is to squash all commits into a single one. Or perhaps squash some of them. Run

git rebase -i master

This command assumes you never touched the master branch, and all work was done within your own branch. It will then open up an editor with something like

pick f564b4c feature
pick 0ea95aa oops
pick 0cbd876 Fixed, finally

The messages and SHA hashes will be different, but you get the list of your changes since your branch diverged from the master. To join all the commits into one, edit like this:

pick f564b4c feature
s 0ea95aa oops
s 0cbd876 Fixed, finally

Here, s means “squash”, that is, combine with the previous commit. Next, an editor with combined commit message pops up. Edit it into a single coherent message and save. Viola! Now you have just one commit. Note that since this is a kind of history rewrite, just like --amend, you'll have to use --force-with-lease to push this history again to GitHub.

Making changes after submitting a PR

You can amend commits and squash them after submitting a PR. The PR will be automatically updated by GitHub. Whatever you do, the PR will always display the difference between the master branch and the latest commit on your feature branch.

Discussing and closing the PR

A PR is sort of a patch attached to a specialized forum topic. It can be discussed, various pieces of code can be reviewed, and it ends either by merging the PR, including your changes in the QuaZIP repo, or closing it without merging if your changes are rejected for whatever reason.

If the PR is successfully merged, you can safely delete your branch. Locally, it is done with

git checkout master
git branch -D your-branch-name
git branch -dr origin/your-branch-name

The first command switches to the master branch (because it would be weird to delete a branch you're currently on), the second one deletes the branch itself, the third one deletes the reference to the remote counterpart in your GitHub account. Note that only the reference is deleted here, the branch itself stays alive and well in your account. To delete it, simply go to the PR and there will be a message saying that the PR is merged with the “delete branch” button right next to it.

Reintegrating the latest upstream changes

Suppose some changes were introduced into the master branch while you were working on your feature. With the traditional send-patch-by-email approach, whoever applies that patch must handle all conflicts (rejected hunks) that arise. With Git, you have a way to fix it before even sending the patch (submitting the PR).

Another situation when you need to pull in the changes from the upstream repo is when you need to submit your next PR, perhaps years later. You still have your old clone (fork) in your GitHub account, and perhaps even a local one on your computer. However, they are probably terribly outdated by now so you need to update them first.

Update procedures are similar in both cases.

1. In either case, you need to make sure you're on the master branch. If it's an old clone, you're probably are, unless you forgot to clean up. If you're working on a feature, you're probably on your feature branch. Make sure your changes are committed before you continue. Then, run

git checkout master

It will bring you back to the master branch.

2. You need to pull in the changes from the upstream repo. The least destructive way to do it is to fetch these changes first:

git fetch upstream

This command just fetches data from the upstream repo, but doesn't touch your working files yet.

3. Next, you better make sure you have no changes with git status. You probably don't if you remembered not to touch the master branch.

4. Pull in the latest commits from the upstream:

git merge upstream/master

This will make your master branch identical the one from the upstream.

5. Push these changes to your GitHub account:

git push origin master

The absence of -u means that Git won't remember that the master branch is connected with origin. That's a good thing because there are two different remote repos for the master branch, and it's much easier to explicitly specify each time where you want to push it to or pull it from rather than remembering which one of the remotes it's associated with.

6. If you were just updating your outdated repo, the procedure ends here. However, if you were already working on a branch that split off from the master before this update, now you need to somehow merge your changes into the new upstream version. There are two ways to do it: merge and rebase. The QuaZIP way is rebase, so rebase you should do. But first, switch to your branch:

git checkout your-feature-branch

7. To merge your changes into the new version, run

git rebase master

This basically says: take the current branch, detach it from where it split from the master, then reattach it to the tip of the new master branch and replay all the changes that were made, making new commits. This leads you to a linear history, where you branch just continues on from the master, instead of splitting from some old version.

If there are merge conflicts, you have to solve them by editing conflicting files, then running git add on them (which in this case just says you're done with conflict solving) and finally running git rebase --continue. There are much more advanced conflict solving techniques which are, again, beyond the scope of this note.