This file describes how to make a 0.3.x maintenance release.


WHY
============

The code in lensfun master has switched to database version 2, but there hasn't been
a new stable release yet and everybody out there is still using the 0.3.x branch.
There hasn't been a new release in the lensfund 0.3.x branch since 0.3.2 in 2015.

The database keeps evolving, but many users don't know they have to run `lensfun-update-data`
to update their local database checkout. Also many distributions ship the 0.3.2 version
without any recent database updates.

Many third-party software packages that rely on the lensfun database also aren't ready to
switch to 0.3.95/0.4.0 and database version 2 yet. darktable for example has some code to
support lensfun 0.3.95, but doesn't reliably build against it.

It is therefore a good a idea to keep shipping 0.3.x maintenance releases that just
contain more recent database snapshots and a few minor fixes. This will also make
people aware that database development continues.


HOW TO MAKE A RELEASE
=====================

1. Clone the lensfun repository. If you already have a local checkout, switch to the master branch instead.


```
git clone git@github.com:lensfun/lensfun.git
```

2. Use the `tools/lensfun_convert_db_v2_to_v1.py` tool to convert the database in `master` to version 1:

```
python3 tools/lensfun_convert_db_v2_to_v1.py /tmp/converted/ data/db/
```

This will create a couple of tarballes in `/tmp/converted/db/`. These are the same tarballs that the `lensfun-update-data` downloads. The code in `lensfun_convert_db_v2_to_v1.py` was ripped out of the script that does the conversion for the webserver `lensfun-update-data` pulls them from.

3. Switch to the `release_0.3.x` branch.

```
git checkout release_0.3.x
```

4. Delete all XML files in `data/db/`.

```
rm data/db/*.xml
```

5. Extract the converted XML files to `data/db/`.

```
tar -xvf /tmp/converted/db/version_1.tar -C data/db/
```

6. Check the database.

```
python3 tools/check_database/check_database.py data/db/
```

7. Check that everything is fine. Build the library, install it locally, test it with an application, etc.

8. Make any other changes, e.g. bugfixes.

9. Add all changed database files to the git staging area and make a commit.

```
git add data/db/*
```

10. Update the Changelog file. You can use the following command to generate a list of supported cameras:

```
xmlstarlet sel -t --var nl -n --break -m "/lensdatabase" -m "camera" --if 'model[@lang="en"]' -v 'concat(maker, " ", model[@lang="en"], $nl)' --else -v 'concat(maker, " ", model, $nl)' --break data/db/*.xml | sort
```

Likewise, the following command will generate a list of supported lenses:

```
xmlstarlet sel -t --var nl -n --break -m "/lensdatabase" -m "lens" --if 'model[@lang="en"]' -v 'concat(maker, " ", model[@lang="en"], $nl)' --else -v 'concat(maker, " ", model, $nl)' --break data/db/*.xml | sort
```

You can use this information to update the ChangeLog.


11. Update the version number in `CMakeLists.txt`.

```
# version
SET(VERSION_MAJOR 0)
SET(VERSION_MINOR 3)
SET(VERSION_MICRO 3)
SET(VERSION_BUGFIX 0)
SET(VERSION_API 1)

```

12. Add `ChangLog`, `CMakeLists` and any other changed files and make a commit.

```
git add Changelog CMakeLists.txt
git commit -m "Release 0.3.3"
```

12. Add a new release tag.

```
git tag v0.3.3
```

13. Push the `release_0.3.x` branch and the new tag to GitHub.

```
git push
git push origin v0.3.3
```

14. Make a new release on GitHub.