Reno was developed by OpenStack: https://docs.openstack.org/reno/latest/
On Sun, Apr 26, 2020 at 5:39 PM Ash Berlin-Taylor <a...@apache.org> wrote: > > 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/>
