|
Packit |
01d647 |
Contributing to the Exiv2 Project
|
|
Packit |
01d647 |
======================
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
# Contents #
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
* [1. Introduction](#1-introduction)
|
|
Packit Service |
fb147c |
* [2. Contributing code via GitHub](#2-contributing-code-via-github)
|
|
Packit Service |
fb147c |
* [3. Contributing code via email](#3-contributing-code-via-email)
|
|
Packit Service |
fb147c |
* [4. Contributing Lens Data](#4-contributing-lens-data)
|
|
Packit Service |
fb147c |
* [5. Reporting Bugs](#5-reporting-bugs)
|
|
Packit Service |
fb147c |
|
|
Packit |
01d647 |
# 1. Introduction #
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
We welcome any help, for example contributing lens data (images), code contributions and bug reports.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
# 2. Contributing code via GitHub #
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Code contributions can be performed via *pull requests* (PR) on GitHub (if you cannot or do not want to use GitHub, see [3. Contributing code via email](#3-contributing-code-via-email)).
|
|
Packit Service |
fb147c |
For this to work you first need to [create a user account on GitHub](https://help.github.com/articles/signing-up-for-a-new-github-account/) if you don't already have one.
|
|
Packit Service |
fb147c |
A pull request should preferable contain only one new feature or bug fix etc. Since it is not uncommon to work on several PRs at the same time
|
|
Packit |
01d647 |
it is recommended to create a new _branch_ for each PR. In this way PRs can easily be separated and the review and merge process becomes cleaner.
|
|
Packit |
01d647 |
As a rule-of-thumb:
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
- PRs should be kept at a manageable size. Try to focus on just one goal per PR. If you find yourself doing several things in a PR that were not expected,
|
|
Packit Service |
fb147c |
then try to split the different tasks into different PRs.
|
|
Packit |
01d647 |
- Commits should always change a *single* logical unit so that cherry-picking & reverting is simple.
|
|
Packit Service |
fb147c |
- Commit messages should be as informative and concise as possible. The first line of the commit message should be < 80 characters and
|
|
Packit Service |
fb147c |
describe the commit briefly. If the 80 characters are too short for a summary, then consider splitting the commit. Optionally, add one blank line
|
|
Packit Service |
fb147c |
below the short summary and write a more detailed explanation if necessary.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
See the [GIT_GUIDELINES.md](git_guidelines.md) file for a more detailed description of the git workflow.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Below we outline the recommended steps in the code contribution workflow. We use `your-username` to refer to your username on GitHub, `exiv2_upstream` is used when we
|
|
Packit Service |
fb147c |
set the upstream remote repository for Exiv2 (we could have picked any name by try to avoid already used names like, in particular, `origin` and `master`), and
|
|
Packit Service |
fb147c |
we use the name `my-new-feature` for the branch that we create (e.g., the branch name should reflect the code change being made).
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
**Important**: If your PR lives for a long time, then don't press the button _Update branch_ in the Pull Request view, instead follow the steps below, as
|
|
Packit |
01d647 |
that avoids additional merge commits.
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
Once you have a GitHub login:
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
1. Fork the Exiv2 git repository to your GitHub account by pressing the _Fork_ button at: [https://github.com/Exiv2/exiv2](https://github.com/Exiv2/exiv2)
|
|
Packit |
01d647 |
(more details [here](https://guides.github.com/activities/forking/)).
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
2. Then start a terminal (or use your favorite git GUI app) and clone your fork of the Exiv2 repo:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git clone https://github.com:your-username/exiv2.git
|
|
Packit |
01d647 |
$ cd exiv2
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
3. Add a new remote pointing to upstream exiv2 repository:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git remote add exiv2_upstream https://github.com/Exiv2/exiv2.git
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
and verify that you have the two remotes configured correctly:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git remote -v
|
|
Packit |
01d647 |
exiv2_upstream https://github.com/Exiv2/exiv2.git (fetch)
|
|
Packit |
01d647 |
exiv2_upstream https://github.com/Exiv2/exiv2.git (push)
|
|
Packit |
01d647 |
origin https://github.com/your-username/exiv2.git (fetch)
|
|
Packit Service |
fb147c |
origin https://github.com/your-username/exiv2.git (push)
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
4. Next, create a branch for your PR from `exiv2_upstream/master` (which we also need to fetch first):
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
$ git fetch exiv2_upstream master
|
|
Packit Service |
fb147c |
$ git checkout -b my-new-feature exiv2_upstream/master --no-track
|
|
Packit Service |
fb147c |
|
|
Packit Service |
fb147c |
NB: This is an important step to avoid draging in old commits!
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
5. Configure the project and check that it builds (if not, please report a bug):
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
$ rm -rf build
|
|
Packit Service |
fb147c |
$ mkdir build && cd build
|
|
Packit Service |
fb147c |
$ cmake -DCMAKE_BUILD_TYPE=Release ..
|
|
Packit Service |
fb147c |
$ make
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
6. Now, make your change(s), add tests for your changes, and commit each change:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
...
|
|
Packit Service |
fb147c |
|
|
Packit |
01d647 |
$ git commit -m "Commit message 1"
|
|
Packit Service |
fb147c |
|
|
Packit |
01d647 |
...
|
|
Packit Service |
fb147c |
|
|
Packit |
01d647 |
$ git commit -m "Commit message 2"
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
7. Make sure the tests pass:
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
$ make tests # Integration tests
|
|
Packit |
01d647 |
$./bin/unit_tests # Unit tests
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Exiv2's (new) test system is described in more detail in the [doc.md](tests/doc.md) and [writing_tests.md](tests/writing_tests.md) files, and a description of the old
|
|
Packit Service |
fb147c |
test system can be found in the Redmine wiki: [How do I run the test suite for Exiv2](http://dev.exiv2.org/projects/exiv2/wiki/How_do_I_run_the_test_suite_for_Exiv2)
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
8. Push the changes to your fork on GitHub:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git push origin my-new-feature
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
9. Create the PR by pressing the _New pull request_ button on: `https://github.com/your-username/exiv2`. Please select the option "Allow edits from maintainers" as outlined
|
|
Packit Service |
fb147c |
[here](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
10. Now wait for an Exiv2 project member(s) to respond to your PR. Follow the discussion on your PR at [GitHub](https://github.com/Exiv2/exiv2/pulls).
|
|
Packit Service |
fb147c |
You may have to do some updates to your PR until it gets accepted.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
11. After the PR has been reviewed you must _rebase_ your repo copy since there may have been several changes to the upstream repository.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Switch to your branch again
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git checkout my-new-feature
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
And rebase it on top of master:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
$ git pull --rebase exiv2_upstream master
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
When you perform a rebase the commit history is rewritten and, therefore, the next time you try to push your branch to your fork repository you will need to use
|
|
Packit Service |
fb147c |
the `--force-with-lease` option:
|
|
Packit Service |
fb147c |
|
|
Packit Service |
fb147c |
$ git push --force-with-lease
|
|
Packit Service |
fb147c |
|
|
Packit Service |
fb147c |
Also, follow the coding guidelines outlined in [CODING_GUIDELINES.md](CODING_GUIDELINES.md).
|
|
Packit Service |
fb147c |
|
|
Packit Service |
fb147c |
# 3. Contributing Code via email #
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
If you cannot or do not want to use GitHub, you can still submit patches via email by using our [sourcehut mirror](https://git.sr.ht/~d4n/exiv2).
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Prepare your changes in your local clone of the [GitHub](https://github.com/Exiv2/exiv2.git) or [sourcehut](https://git.sr.ht/~d4n/exiv2) repository following our
|
|
Packit Service |
fb147c |
[CODING_GUIDELINES.md](CODING_GUIDELINES.md) and [GIT_GUIDELINES.md](git_guidelines.md). Send your patches to the
|
|
Packit Service |
fb147c |
[~d4n/exiv2-patches@lists.sr.ht](mailto:~d4n/exiv2-patches@lists.sr.ht) mailing list. Please use `git send-email` as outlined in https://git-send-email.io/ to
|
|
Packit Service |
fb147c |
simplify the integration of your patches.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
# 4. Contributing Lens Data #
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
In order for the Exiv2 project to support a new lens we need an example image containing the Exif metadata of that lens. This is a good way for
|
|
Packit |
01d647 |
non-programmers to contribute to the project and example images can be submitted using the following procedure:
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
1. Create a new Issue by pressing the _New issue_ button here: [https://github.com/Exiv2/exiv2/issues](https://github.com/Exiv2/exiv2/issues),
|
|
Packit |
01d647 |
2. In the new Issue, enter/add the lens mount and full lens name for each lens,
|
|
Packit |
01d647 |
3. Take a (small) .jpg image (with the lens cap on) with each lens and transfer the .jpg file(s) to disk __without processing it__ in a desktop or server software (this is important to preserve the exif metadata in the file),
|
|
Packit Service |
fb147c |
4. Attach the .jpg image(s) to the Issue (one can just drag-and-drop the image(s) or paste it/them from the clipboard).
|
|
Packit |
01d647 |
|
|
Packit |
01d647 |
Note that we are not only interested in non-supported lenses since we also look for example images to expand and improve the Exiv2 code tests.
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
# 5. Reporting Bugs #
|
|
Packit |
01d647 |
|
|
Packit Service |
fb147c |
Bugs should be reported by creating Issues on GitHub. However, before reporting a bug first check the Issue list if the bug is already known, and only if you cannot find any previous bug report
|
|
Packit Service |
fb147c |
then create a new Issue. When reporting a bug try to describe the problem in as much detail as possible and if the bug is triggered by an input file then attach that file to the GitHub Issue, too.
|