Page 1 of 3

Changelog

Posted: 16 May 2018, 08:39
by psi29a
Should we be keeping a changelog?

Something along the lines of, when there is non-trivial commit, bug-fix or new feature, that we require the author of the PR to add an entry into the changelog along with link to PR?

We can base the changelog around changes since last release that includes sections for: new-features, bug-fixes, API changes in supporting libraries (and more).

This would help:
* decrease the time preparing release because the changelog is more or less ready
* better house-keeping, we can link a change back to a PR in-case there are issues
* give a better overview of work for those interested, and helps downstream news/media/press dig into what is new

This isn't bullet-proof and requires little additional effort from the PR author, but is really handy with our long development cycles.

What do you think?

Re: Changelog

Posted: 16 May 2018, 09:35
by raevol
I'm not exactly sure I understand what you mean, because I am reading this really tired, but it sounds like a really good idea. Let me know if I can help in any way.

Re: Changelog

Posted: 16 May 2018, 09:58
by psi29a
That we maintain a CHANGELOG file... either in our docs or in the root directory that details, per-release the changes that have been made.

For example:
https://txmongo.readthedocs.io/en/latest/NEWS.html
and
https://github.com/pyca/cryptography/bl ... NGELOG.rst

UNRELEASED is a placeholder where devs can put their changes in, during the release process, you would need to update that with the date.

Notice sub-headers: bug-fixes, features, api-changes, etc. We don't have to be so anal-retentive, but we could split up the fixes according to openmw, openmw-cs, components/libs, extern deps...

Re: Changelog

Posted: 16 May 2018, 19:51
by raevol
Yea, sounds good to me. What would trigger adding a changelog entry? Merging a pull request? How would we make sure no merges slip through the cracks?

Re: Changelog

Posted: 16 May 2018, 20:09
by psi29a
Would be a requirement for a PR. No changelog entry, no mergy mergy. ;)

Not a hard-rule, some trivial things don't matter... typos, refactors. Those of us with ability to commit to master on openmw will probably have to get into the habit of updating the changelog as well.

Re: Changelog

Posted: 16 May 2018, 20:20
by raevol
Sounds good to me...

Re: Changelog

Posted: 16 May 2018, 21:02
by Capostrophic
I fear the merge conflicts that might arise...

Re: Changelog

Posted: 16 May 2018, 21:04
by psi29a
Been doing this for years with otherr projects, never had an issue with this.

Re: Changelog

Posted: 17 May 2018, 12:29
by Zini
Sorry, I fail to see what the point of this change is. Our current procedure seems to work fine IMO.
decrease the time preparing release because the changelog is more or less ready
Not really an issue. Now my time is very limited these days, but updating the change log once every could of month I still can handle without problems.
better house-keeping, we can link a change back to a PR in-case there are issues
We have that. Okay, it is not a clickable link, but the changelog contains the issue number which is easy to find. If we make changes in this direction we should focus on making sure the PR is properly linked with the issue.
give a better overview of work for those interested, and helps downstream news/media/press dig into what is new
Again, we have that. The current milestone on the tracker.

Re: Changelog

Posted: 17 May 2018, 13:47
by psi29a
If you think that it's a none-issue, that's fine.

I just wanted to help reduce the time spent on creating the changelog during release by making it the developer's job to update the changelog when they complete a feature or fix a bug. Many helping hands, changing one line, does short work.