New upstream version 0.7.6

/doc

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](https://github.com/stachenov/quazip/issues).

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.

# This could be handy for archiving the generated documentation or

# if some version control system is used.

PROJECT_NUMBER         = quazip-0-7-3

PROJECT_NUMBER         = quazip-0-7-6

# Using the PROJECT_BRIEF tag one can provide an optional one line description

# for a project that appears at the top of each page and should give viewer

EXCLUDE                = quazip/unzip.h \

                         quazip/zip.h \

                         quazip/ioapi.h \

                         quazip/crypt.h \

                         quazip/minizip_crypt.h \

                         qztest/

# The EXCLUDE_SYMLINKS tag can be used select whether or not files or

# If a tag file is not located in the directory in which doxygen

# is run, you must also specify the path to the tagfile here.

TAGFILES               = qtcore.tags=http://doc.qt.io/qt-5/

TAGFILES               = qtcore.tags=http://doc.qt.io/qt-5.9/

# When a file name is specified after GENERATE_TAGFILE, doxygen will create

# a tag file that is based on the input files it reads.

QuaZIP changes

* 2018-06-13 0.7.6

        * Fixed the Zip Slip vulnerability in JlCompress

        * Renamed crypt.h to minizip_crypt.h to avoid conflicts

* 2018-05-20 0.7.5

        * Fixed target_link_libraries call in CMakeLists

        * Worked around a Qt 4.6 bug (QTBUG-15421) screwing up hidden

          files handling in JlCompress::compressDir()

        * Removed Q_FOREACH uses to avoid conflicts (SF patch #32)

* 2017-02-05 0.7.4

        * Static analysis patch from Intel Deutschland GmbH

        * Replaced UNUSED with QUAZIP_UNUSED to avoid name clashes

        * Minor bug fixes

* 2017-02-05 0.7.3

        * Symlink handling

        * Static linking exception for LGPL

QuaZIP is the C++ wrapper for Gilles Vollant's ZIP/UNZIP package

(AKA Minizip) using Trolltech's Qt library.

If you need to write files to a ZIP archive or read files from one

using QIODevice API, QuaZIP is exactly the kind of tool you need.

See [the documentation](https://stachenov.github.io/quazip/) for details.

Want to report a bug or ask for a feature? Open an [issue](https://github.com/stachenov/quazip/issues).

Want to fix a bug or implement a new feature? See [CONTRIBUTING.md](CONTRIBUTING.md).

Copyright notice:

Copyright (C) 2005-2018 Sergey A. Tachenov

Distributed under LGPL, full details in the COPYING file.

Original ZIP package is copyrighted by Gilles Vollant, see

quazip/(un)zip.h files for details, but basically it's the zlib license.