Yeah, probably is overly complex for general changelog. The main thing updating.md needs is some concept of knowing which release it is in when the commit appears in multiple branches (but with different commit IDs because of cherry picking.) Sure we could write the tooling for that, but someone already has.
(I think it's for Openstack? I'll find the link on Monday) I'd say let's keep updating.md out of the discussion for now On 26 April 2020 16:15:18 BST, Jarek Potiuk <jarek.pot...@polidea.com> wrote: >> >> >> For changelog there is another option, which is a more formal/complex >> system which works better with our backport/release branch process. >(Can't >> find the specific tool I'm thinking of from my phone. It involves >each >> change note in a separate file, and then a script to compile it. >Roughly) >> That may be better suited to UPDATING.md though >> > >I think overhead for that would be very, very painful for regular >changes. >We already have the commit message - so why don't we simply use it >better. > >BTW. The commitizen + semantic commits already have a way to handle >BREAKING CHANGES- they are put in the footer with "breaking changes" >prefix >and you can put the right description there (and it can be used to add >them >to changelog/updating.md updates). Here I am on the fence if we should >use >it or not - because `git annotate` on UPDATING.md has already all info >that >is needed, but maybe we can discuss the approach here as well. > >J. > > > >> >> -a >> >> On 26 April 2020 14:38:17 BST, Tomasz Urbaszek <turbas...@apache.org> >> wrote: >> >I agree with Ash that it's a committer's task to check the commit >name. >> >But >> >I personally was deceived by a discrepancy between PR name and >commit >> >title >> >and merged the PR with "wrong" commit message. >> > >> >That's where I agree with Jarek: we should help ourselves. If "red >> >check" >> >will make people correct the commit / PR title then there will be >less >> >work >> >for us and fewer mistakes made by us. Also, semantic commits have a >> >nice >> >side effect: they teach about commit messages. I think having a tool >to >> >check and teach is better having a "you should follow this" link, >which >> >in >> >most cases is ticked without clicking the link (btw. should we >measure >> >it?). >> > >> >One of my reason to suggest it was a conventional changelog that >could >> >be >> >auto-generated. As Jarek mentioned currently it's mostly done by >@Kaxil >> >and >> >it would be interesting to hear what he thinks about it. >> > >> >T. >> > >> >On Sun, Apr 26, 2020 at 2:44 PM Jarek Potiuk ><jarek.pot...@polidea.com> >> >wrote: >> > >> >> I think you pointed out the exact things I thought are important >and >> >could >> >> be automated. I think those are the very things committing checks >> >for. >> >> >> >> I think we could benefit from 1, 2, 3, 4, 6 (6. with exceptions >> >indeed but >> >> a warning or a way to mark an exception would be nice - similarly >as >> >we do >> >> with pylint). >> >> I certainly did not want to improve automatically on the 5 (yet) >and >> >7 >> >> (here it's much more of a convention we agree between the >committers >> >- >> >> whether the body should be optional - I think it should and >whether >> >it >> >> should be opt-out rather than opt-in - I thin it should be >opt-out). >> >> >> >> There are quite a few commits currently with ... when you look at >> >> the commit log in Github for one (because they do not obey the >> >subject >> >> length) - I picked the ones without JIRAs - still even without >JIRAs >> >> sometimes the subject is too long: >> >> >> >> - >> >> >> >> >> > >> >https://github.com/apache/airflow/commit/d883ff49ca2841f91ab7e0ab98204d5ad271473b >> >> - >> >> >> >> >> > >> >https://github.com/apache/airflow/commit/bc230a9711fec2004e20f46aee22fb44c7461b6c >> >> - >> >> >> >> >> > >> >https://github.com/apache/airflow/commit/fa262c12f87102a7ae1abb11ea7f0d5e8be0de47 >> >> >> >> However - this is secondary. It was merely a comment on the >possible >> >> completion of the "semantic convention" approach. This is the main >> >subject. >> >> >> >> I think the main idea behind the semantic commit/PR is the prefix >is >> >that >> >> it allows for much easier and consistent ChangeLog generation. For >> >example >> >> in Angular you have >> >> https://github.com/angular/angular/blob/master/CHANGELOG.md which >is >> >> generated automatically including breaking changes etc. I think >it's >> >> mainly Kaxil's work now to prepare the changelog and group the >> >changes into >> >> separate buckets, so Kaxil - maybe your opinion is important here. >If >> >there >> >> is a way everyone as committers and contributors we can do to make >> >release >> >> manager's job easier - I think we should do it. >> >> >> >> BTW. The convention is easy to follow without any tools. However >> >commitizen >> >> has the nice feature of also guiding new users - it provides a >nice >> >> explanation of the types you have defined in the project and guide >> >the new >> >> users how to write a good commit. I think it might be really nice >> >touch for >> >> our "welcoming community" approach. See the 5 minutes video about >it: >> >> >> >> >> > >> >https://egghead.io/lessons/javascript-writing-conventional-commits-with-commitizen >> >> >> >> J. >> >> >> >> J. >> >> >> >> >> >> >> >> On Sun, Apr 26, 2020 at 2:13 PM Ash Berlin-Taylor <a...@apache.org> >> >wrote: >> >> >> >> > My main objection is this is trying to apply a technical >solution >> >to a >> >> > people+English problem. This feels like just one extra step to >have >> >> > commiters to do, when we as committers can very easily correct >this >> >in >> >> > Github whilst reviewing/before merging. >> >> > >> >> > That said, can you point at any examples of recent commits that >you >> >> > think would have been clearer as a result of using? >> >> > >> >> > (Also a significant proportion of commits from form a git gui or >an >> >ide, >> >> > so cz-cli won't help those users.) >> >> > >> >> > The "good commit messages" we already link to >> >> > https://chris.beams.io/posts/git-commit/ has these points >> >> > >> >> > 1. Separate subject from body with a blank line >> >> > 2. Limit the subject line to 50 characters >> >> > 3. Capitalize the subject line >> >> > 4. Do not end the subject line with a period >> >> > 5. Use the imperative mood in the subject line >> >> > 6. Wrap the body at 72 characters >> >> > 7. Use the body to explain what and why vs. how >> >> > >> >> > 2 we _could_ enforce, but it is not a hard-and-fast rule. 5 and >7 >> >is >> >> > almost impossible for a computer to enforce. 6 always has >> >exceptions. >> >> > The most important ones is 7, and that is the hardest to >> >programitcally >> >> > enforce. >> >> > >> >> > -a >> >> > >> >> > On Apr 26 2020, at 11:30 am, Jarek Potiuk >> ><jarek.pot...@polidea.com> >> >> > wrote: >> >> > >> >> > > I think it's a very good idea to use it. We already discussed >> >that we >> >> > > should have some improvements in the way we write commits - >and >> >why to >> >> > > come up with our own conventions if we can adopt one that >already >> >> > > exists and has set of nice tools available. >> >> > > >> >> > > As usual, I think automation is a key - as it might make lives >of >> >> > > committers a bit easier. There are already a number of tools >that >> >we >> >> > > could use together with such convention, as both pre-commits >and >> >a bot >> >> > > in Github. >> >> > > There are quite a few tools that embraced the concept of >semantic >> >> > > pr/semantic commits and I have heard good words about them >from >> >other >> >> > > open-source projects. I've heard especially good words about >> >> > > commitizen CLI, that could work hand-in-hand with semantic >> >> > > commits/PRs: >> >> > > >> >> > > https://github.com/commitizen/cz-cli >> >> > > >> >> > > One of the things it has it also integrates with commit lint >> >where we >> >> > > could write our own rules and make them more meaningful >> >> > > https://commitlint.js.org/#/ >> >> > > >> >> > > Also, there are ready-to-use changelog generators that we can >use >> >(for >> >> > > example >https://github.com/commitizen/cz-conventional-changelog ) >> >> > > >> >> > > Those are tools coming from the nodejs world, but I do not see >a >> >big >> >> > > problem with using them (of course trying them out first) - >since >> >we >> >> > > can now connect it via pre-commit, it should be easy to add >all >> >that >> >> > > to our toolbox. >> >> > > >> >> > > J. >> >> > > >> >> > > >> >> > > On Sun, Apr 26, 2020 at 10:44 AM Ash Berlin-Taylor >> ><a...@apache.org> >> >> > wrote: >> >> > >> >> >> > >> I agree that many commit messages are often lacking but I'm >not >> >a fan >> >> > >> of that the prefix style that app requires, - plus I think it >> >would >> >> > >> still be possible to have unhelpful PR titles just with >'fix:' >> >> prefixed. >> >> > >> >> >> > >> Is rather we as commiters updated the pr subjects when >> >reviewing. The >> >> > >> rule I try to follow is to (mentally) prefix the message with >> >"When >> >> > >> this commit is applied it will ..." >> >> > >> >> >> > >> -a >> >> > >> >> >> > >> On 26 April 2020 09:34:56 BST, Tomasz Urbaszek >> ><turbas...@apache.org> >> >> > wrote: >> >> > >> >Hi all! >> >> > >> > >> >> > >> >Sometimes it happens that pull requests or commits have not >so >> >> > >> >meaningful messages and it's hard to say what's exactly >going >> >on. >> >> > >> >So I am wondering if we would like to consider using >semantic >> >pull >> >> > >> >request: https://github.com/zeke/semantic-pull-requests >> >> > >> > >> >> > >> >Since we are using Github it should be pretty easy to add: >> >> > >> >https://github.com/apps/semantic-pull-requests >> >> > >> > >> >> > >> >Of course, it does not solve the problem of "pr message" but >> >> > >> >definitely it raises attention about it. On the other hand, >it >> >should >> >> > >> >also help with publishing changelogs. Personally I like this >> >approach >> >> > >> >and I used to use it before joining Airflow. >> >> > >> > >> >> > >> >Happy to see what you think about it. And sorry if it was >> >decided >> >> some >> >> > >> >ago that Airflow won't follow it. >> >> > >> > >> >> > >> >Cheers, >> >> > >> >Tomek >> >> > > >> >> > > >> >> > > >> >> > > -- >> >> > > >> >> > > Jarek Potiuk >> >> > > Polidea | Principal Software Engineer >> >> > > >> >> > > M: +48 660 796 129 >> >> > > >> >> > >> >> >> >> >> >> -- >> >> >> >> Jarek Potiuk >> >> Polidea <https://www.polidea.com/> | Principal Software Engineer >> >> >> >> M: +48 660 796 129 <+48660796129> >> >> [image: Polidea] <https://www.polidea.com/> >> >> >> > > >-- > >Jarek Potiuk >Polidea <https://www.polidea.com/> | Principal Software Engineer > >M: +48 660 796 129 <+48660796129> >[image: Polidea] <https://www.polidea.com/>
