Changelog

Everything about development and the OpenMW source code.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Changelog

Post 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?
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Changelog

Post 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.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Changelog

Post 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...
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Changelog

Post 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?
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Changelog

Post 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.
User avatar
raevol
Posts: 3093
Joined: 07 Aug 2011, 01:12
Location: Caldera

Re: Changelog

Post by raevol »

Sounds good to me...
User avatar
Capostrophic
Posts: 794
Joined: 22 Feb 2016, 20:32

Re: Changelog

Post by Capostrophic »

I fear the merge conflicts that might arise...
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Changelog

Post by psi29a »

Been doing this for years with otherr projects, never had an issue with this.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Changelog

Post 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.
User avatar
psi29a
Posts: 5356
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Changelog

Post 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.
Post Reply