Add a CHANGELOG.md

[millerdev]

I attempted to review the changes between 1.6.0 and 1.7.0, but found it difficult aside from looking at commit history, which is somewhat hard to piece together to get the bigger picture. A change log would be a nice addition.

[DimitriPapadopoulos]

What's the expected level of detail of the change log? Obviously we could filter out part of the commit history, such as typo fixes. Eventually it might be better to use tags in commits or even use some strict discipline in commits (but then it would mean extra work).

[millerdev]

Things to include for each new release version, in order of importance:

• backward incompatible changes
• known issues
• new features
• bug fixes

Each item in a change log should be a high-level overview of the change, consumable by end users.

[mrbaseman]

New features and bug fixes should be possible to extract from the commit history. I admit that the commit history is not always that easy to follow by end users, so before tagging a new release we could update a high level CHANGELOG.md file. That's of course some extra work we would have to do.

The other two items are more difficult. Known issues are present on github, maybe we can just include a link for this. The problem is that on some platform there may be "unknown issues" when we tag a release, which we notice shortly after that and which would be in the online issues list, but not in a file at a specific tag level.

We try hard to avoid backward incompatible changes (yes, we had at least one that I'm aware of), but the same as for the known issues: It may turn out that some changes are incompatible for some very specific configurations which we are not aware of until someone opens an issue about it. So, basically, that's the same problem as with the known issues.

[adrienverge]

A high level CHANGELOG file would be a real plus, but also laborious to maintain. Is anyone willing to take the lead on this? It requires updating the file at each new release.

[mrbaseman]

well, the file should be updated either before each release, or with every commit that is worth to mention there. I have attempted to extract the information from the submit history in #393 . I have skipped minor bug fixes and fixes to commits younger than the latest release in this high-level view. However, it's difficult to decide where to draw the border, so any corrections are welcome.

[adrienverge]

Most projects I know update their changelog when pushing a release: this is less time-consuming, and this is the most useful for users, I think. Users that build openfortivpn from master will expect differences from the last changelog update, I think.

[mrbaseman]

Ok, so I can do this task. For now I have focused on the recent changes in #393 but as time allows I can go back in the commit history and put more high level summaries for older releases into CHANGELOG.md.

BTW, tagging a new release is simply done by increasing the version number in configure.ac, right? So a workflow could be to create a pull request with an updated CHANGELOG.md and configure.ac, then we can discuss it on github, and finally you, @adrienverge merge that PR.

[adrienverge]

The workflow you describe seems perfect.

We just have to be careful to keep following semver: increase the minor version when there are new features; increse the patch version when there are only bug fixes.

[mrbaseman]

Sure. This time we have a couple of new features, so it will become the 1.8.0 release.
We can use #393 right away - I'll push the update of the release number to this branch.

[mrbaseman]

The recently issued version 1.8.0 contains a CHANGELOG.md. I assume that we can close this issue now. For future releases I'm going to update this file, and I have it on my agenda eventually to add high-level descriptions about older versions, too.

[mrbaseman]

For the record: I went through the issues list and for those which are fixed with version 1.8.0 I have added a comment about that.