We welcome any help, for example contributing lens data (images), code contributions and bug reports.
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). For this to work you first need to create a user account on GitHub if you don't already have one. 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 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. As a rule-of-thumb:
See the GIT_GUIDELINES.md file for a more detailed description of the git workflow.
Below we outline the recommended steps in the code contribution
workflow. We use
your-username to refer to your username on
exiv2_upstream is used when we set the upstream
remote repository for Exiv2 (we could have picked any name by try to
avoid already used names like, in particular,
master), and we use the name
for the branch that we create (e.g., the branch name should reflect the
code change being made).
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 that avoids additional merge commits.
Once you have a GitHub login:
Fork the Exiv2 git repository to your GitHub account by pressing the Fork button at: https://github.com/Exiv2/exiv2 (more details here).
Then start a terminal (or use your favorite git GUI app) and clone your fork of the Exiv2 repo:
$ git clone https://github.com:your-username/exiv2.git $ cd exiv2
Add a new remote pointing to upstream exiv2 repository:
$ git remote add exiv2_upstream https://github.com/Exiv2/exiv2.git
and verify that you have the two remotes configured correctly:
$ git remote -v exiv2_upstream https://github.com/Exiv2/exiv2.git (fetch) exiv2_upstream https://github.com/Exiv2/exiv2.git (push) origin https://github.com/your-username/exiv2.git (fetch) origin https://github.com/your-username/exiv2.git (push)
Next, create a branch for your PR from
exiv2_upstream/master (which we also need to fetch
$ git fetch exiv2_upstream master $ git checkout -b my-new-feature exiv2_upstream/master --no-track
NB: This is an important step to avoid draging in old commits!
Configure the project and check that it builds (if not, please report a bug):
$ rm -rf build $ mkdir build && cd build $ cmake -DCMAKE_BUILD_TYPE=Release .. $ make
Now, make your change(s), add tests for your changes, and commit each change:
... $ git commit -m "Commit message 1" ... $ git commit -m "Commit message 2"
Make sure the tests pass:
$ make tests # Integration tests $./bin/unit_tests # Unit tests
Exiv2's (new) test system is described in more detail in the doc.md and writing_tests.md files, and a description of the old test system can be found in the Redmine wiki: How do I run the test suite for Exiv2
Push the changes to your fork on GitHub:
$ git push origin my-new-feature
Create the PR by pressing the New pull request button
https://github.com/your-username/exiv2. Please select
the option "Allow edits from maintainers" as outlined here.
Now wait for an Exiv2 project member(s) to respond to your PR. Follow the discussion on your PR at GitHub. You may have to do some updates to your PR until it gets accepted.
After the PR has been reviewed you must rebase your repo copy since there may have been several changes to the upstream repository.
Switch to your branch again
$ git checkout my-new-feature
And rebase it on top of master:
$ git pull --rebase exiv2_upstream master
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 the
$ git push --force-with-lease
Also, follow the coding guidelines outlined in CODING_GUIDELINES.md.
If you cannot or do not want to use GitHub, you can still submit patches via email by using our sourcehut mirror.
Prepare your changes in your local clone of the GitHub or sourcehut repository following
our CODING_GUIDELINES.md and GIT_GUIDELINES.md. Send your patches to the
mailing list. Please use
git send-email as outlined in https://git-send-email.io/ to
simplify the integration of your patches.
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 non-programmers to contribute to the project and example images can be submitted using the following procedure:
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.
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 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.