Yii2: Automate handling of CHANGELOG

[arogachev]

Current handling of CHANGELOG has some problems:

• User has to manually insert according line in CHANGELOG:
  
  
  
  • one additional action for user;
  
  
  • can be forgotten by user;
  
  
  • title or issue's number can be distorted by user;
  
  
  • one additional thing for reviewers to check or same action to do during PR review. Human factor also applies here.
  
  
• Merge conflicts when PR is still not merged but CHANGELOG is modified on "master" branch. Requires additional commits to merge "master" and resolve this conflict.
• Lines need to be inserted in the right section and placed in order with existing lines. Because of the human factor, for example, one redundant symbol can break the order or line can be inserted in the wrong place and reviewers can skip it. This requires additional commits for fixing.

Recently I contributed to Jekyll with some minor fixes and was amazed how elegantly CHANGELOG is handled there.

See for example this PR - https://github.com/jekyll/jekyll/pull/5819.

So we can delegate dirty work to our already existing bot (hi, @yii-bot! :smile:). I see the process like this:

1) When issue is confirmed for implementing, fix the title if it has some problems. With this we are killing two birds with one stone - not only it will be more readable, intuitive and easier to find, it also will be prepared for inserting in the CHANGELOG.

2) When PR is reviewed and ready for merge, use the similar command something like:

@yii-bot merge +docs

We can use status tag of the related issue for determining the section for insertion, for example, "bug", "enhacement", etc.

And that's it! No longer we need to worry about related mess and hassle.

[samdark]

That's an interesting approach...

[samdark]

@cebe what do you think?

[TerraSkye]

Any additional thoughts about this?

[cebe]

coming, when we have time for it ;)

[TerraSkye]

Ok perfect!

[dynasource]

@arogachev, great proposition

[arogachev]

One more proposal related with this is to stop accepting PRs with no related issue created beforehand, like this: #13340. This is inconsistent with common workflow. In issue we expect to see the actual problem, can discuss it, is it needed, pros and cons, possible variants of implementations. In PR - review the concrete solution / implementation. These 2 should not be mixed.

Automating can help to solve this problem too and make workflow more strict.

[Kolyunya]

stop accepting PRs with no related issue created beforehand

@arogachev do you really want us to create issues for PRs like this?

[dynasource]

good point. This is a good indication for the different types of PR's we have. IMO, not all PR's deserve a registration in the changelog such as:

• typo's
• doc extensions
• refactorings etc.

All other changes do deserve communication to the community and should be supported with an issue created.

• solving issues
• adding features

The above setup fits @arogachev workflow suggestions quite well

[arogachev]

@Kolyunya Obviously no. Only for changes which contains code fixes / improvements and therefore needs to be reflected in CHANGELOG,

[samdark]

I think for some pull requests it makes sense to omit creating an issue even if it should be in the changelog.

[samdark]

Omitting issue doesn't mean one should not describe the problem in the pull request description. The goal of the issue is to discuss prior to starting a pull request because issue may be invalid and PR may be rejected because of that wasting contributor's time.

[cebe]

opencv also has a bot for code formatting: https://github.com/opencv-pushbot https://github.com/opencv/opencv/commits/master?author=opencv-pushbot

[samdark]

Not critical. Won't do for 2.0.