URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: opened
PR body: """ This commits add information on several tags that should be used so we are able to generate release notes on each new release automatically. This will make release notes more thorough and it will also simplify the process a lot since it take lots of time to do it manually.
Why I chose `:tag:` format> 1. Using @ notation creates user references in github so I wanted to use something different. 2. Using a plain text like (Resolves) leads people to create their own variations (Fixes, Resolves XYZ, ...) which adds additional burden to maintainers. Using this format makes it less error prone and easier to parse. """
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: edited
Changed field: body Original value: """ This commits add information on several tags that should be used so we are able to generate release notes on each new release automatically. This will make release notes more thorough and it will also simplify the process a lot since it take lots of time to do it manually.
Why I chose `:tag:` format> 1. Using @ notation creates user references in github so I wanted to use something different. 2. Using a plain text like (Resolves) leads people to create their own variations (Fixes, Resolves XYZ, ...) which adds additional burden to maintainers. Using this format makes it less error prone and easier to parse. """
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: +Waiting for review
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
sumit-bose commented: """ Hi,
thanks, I think this is a really good idea.
I'm fine with the tag format. Are you aware of other projects using a similar approach to auto-generate the release notes?
I wonder if it would make sense to add the most common tags already to the boiler-plate as a reminder like e.g-
COMPONENT: Subject
:relnote: :feature: :bug: Explanation
Resolves: https://github.com/SSSD/sssd/issues/XXXX
bye, Sumit """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-668487918
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Most of the tickets don't require release notes so I'm not sure if this would be helpful but I don't have a strong opinion on it. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-668504569
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ I updated the patch. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-668512159
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
elkoniu commented: """ I remember that on Gerrit it was possible to put some git hooks in place to forbid pushing pull requests with wrong format of commit message. Not sure if GitHub supports this but it may be a part of CI testing each PR (if it is not already). """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-669526558
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
ikerexxe commented: """
I like this change but for me those ":title:" looks bit exotic and easy to mistype. Some kinds of fonts use to show ":" quite poor way. How about something bigger like "[]", "<>" or "##"? ":" may be used as some field separator. We already using it in commit title.
Other than that LGTM
I agree that using `:` isn't a very good idea. Moreover, I don't think we can use `#` as a tag because it can be mistaken as a commit message comment. I like the idea of using `[]`, though. They aren't very used characters and they are very easy to locate for the human eye. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-669803431
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ I don't insist on any specific format. I chose `:tag:` because it is being using in [ReST format](https://docutils.sourceforge.io/docs/ref/rst/roles.html) so it is something common. Iker is right, `#` can't be used because it is interpreted as comment by git so it will not be added to the message. `[]` is widely used in debug messages which are often part of commit message, `<>` are widely used in shell and in output of many programs which we often append to the commit message so in both cases, collisions (even though unlikely) or confusion may happen. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-670055330
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
thalman commented: """ Great idea! I like it.
"""
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-671421198
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ I don't insist on any specific format. I chose `:tag:` because it is being used in [ReST format](https://docutils.sourceforge.io/docs/ref/rst/roles.html) so it is something common. Iker is right, `#` can't be used because it is interpreted as comment by git so it will not be added to the message. `[]` is widely used in debug messages which are often part of commit message, `<>` are widely used in shell and in output of many programs which we often append to the commit message so in both cases, collisions (even though unlikely) or confusion may happen. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-670055330
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ When I submitted a contribution to Ansible, they wanted me to provide a [release notes fragment](https://github.com/ansible/ansible/tree/devel/changelogs). Little digging revealed that they are using a tool [reno](https://docs.openstack.org/reno/latest/user/usage.html) developed by Openstack. The idea is similar to what I suggested but instead of describing the changes in a commit message you describe it in a file. The files are deleted with new release. One of the advantages in this approach is that it can actually detect that a patch was reverted (the file is not present anymore) and you can fix typos any time which would be hard if it is in commit message.
I believe this is worth trying out. We wouldn't have to implement the parser ourselves, it seems to be flexible and it can be directly integrated with sphinx. It would also make it easier to provide more granularity as Pawel suggested. And of course we will not be hitting this silly conflict with emojis :-) """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-674039408
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
elkoniu commented: """ I like the idea. So it works like some journal file where each commit adds record about changes and then this file is consumed by release and cleaned?
pt., 14 sie 2020, 13:57 użytkownik Pavel Březina notifications@github.com napisał:
When I submitted a contribution to Ansible, they wanted me to provide a release notes fragment https://github.com/ansible/ansible/tree/devel/changelogs. Little digging revealed that they are using a tool reno https://docs.openstack.org/reno/latest/user/usage.html developed by Openstack. The idea is similar to what I suggested but instead of describing the changes in a commit message you describe it in a file. The files are deleted with new release. One of the advantages in this approach is that it can actually detect that a patch was reverted (the file is not present anymore) and you can fix typos any time which would be hard if it is in commit message.
I believe this is worth trying out. We wouldn't have to implement the parser ourselves, it seems to be flexible and it can be directly integrated with sphinx. It would also make it easier to provide more granularity as Pawel suggested. And of course we will not be hitting this silly conflict with emojis :-)
— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/SSSD/sssd/pull/5257#issuecomment-674039408, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARUPLG5OB4FG6F3WYSM64TSAURD5ANCNFSM4PLO374Q .
"""
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-674358906
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
elkoniu commented: """ I like the idea. So it works like some journal file where each commit adds record about changes and then this file is consumed by release and cleaned?
"""
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-674358906
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
sumit-bose commented: """ Hi,
I'm all in favor using a scheme/tool other projects are using as well.
bye, Sumit """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-674871862
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
elkoniu commented: """
When I submitted a contribution to Ansible, they wanted me to provide a [release notes fragment](https://github.com/ansible/ansible/tree/devel/changelogs). Little digging revealed that they are using a tool [reno](https://docs.openstack.org/reno/latest/user/usage.html) developed by Openstack. The idea is similar to what I suggested but instead of describing the changes in a commit message you describe it in a file. The files are deleted with new release. One of the advantages in this approach is that it can actually detect that a patch was reverted (the file is not present anymore) and you can fix typos any time which would be hard if it is in commit message.
I believe this is worth trying out. We wouldn't have to implement the parser ourselves, it seems to be flexible and it can be directly integrated with sphinx. It would also make it easier to provide more granularity as Pawel suggested. And of course we will not be hitting this silly conflict with emojis :-)
To summarize I think we may stick with this idea and start playing with it. One thing is that some howto will be needed for sure or some example in our documentation. Also I am thinking if it is possible to put some automation in creating those files using some git hooks? We should try to avoid situation where we may have to bounce off community contributions due to some missing side data for our automation. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-675062463
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ I did lots of research on the topic. Ansible replaced `reno` with its own generator `antsibull-changelog` that is quite closely bound to Ansible development and cannot be used by unrelated projects. I also looked for other generators, most of them is just using git commit message (and only the subject line), many of them are tightly bound to the language and packaging system (most often pip or npm) so those can not be used.
`reno` itself seemed promising but there are some limitations that do not work for us. * One of the biggest caveats is that it actually requires the relnote files to be never deleted. Once deleted, the release notes is also lost from the history when regenerating older release notes. So reverting a patch after a release would remove it from the old release notes as well so automation gets broken. * IMHO keeping dozens and later hundreds of release notes in the tree forever is not cool. * It uses tag name as the version name, this does not work for us since we use sssd-X_Y_Z instead of sssd-X.Y.Z for some reason. * Another thing is that `reno` attaches a unique id to each file so it is kind of required to use `reno new slug` by contributors which is unnecessary I think. It seem to work even without the id, but that would be prone to conflicts if we need to keep the files around.
So what I would like to do is to keep the idea of putting the notes into yaml files into the repository but always delete them after the release. And prepare a custom generator that will fit our needs. It's just a few minutes work in Python, so it really does not matter. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-676535344
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Or we can of course ask openstack developers if they would accept contributions. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-676536711
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Or we can of course ask openstack developers if they would accept contributions.
EDIT: Looking at the code, this would take lots of time to implement different logic there. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-676536711
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
alexey-tikhonov commented: """ I think I liked idea of tags in commit message more. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-676595114
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ I must admit I'd also prefer it inside the commit message. How about combining both worlds:
``` SUBJECT: lorem ipsum
Commit message.
'''sssd-relnotes fixes: - fix description ''' ```
+ easy to parse, just treat the block as yaml + it is clear how to use it + reverted patches can be detected + no extra files in repositor - it is not possible to update or remove the commit message once pushed """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-677494749
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ See updated commit template. I changed a description a lot, hopefully it is now clear. Tags do not conflict with any emoji now. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-687084337
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
sumit-bose commented: """ Hi,
I'm fine with the current version.
bye, Sumit """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702192181
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
thalman commented: """ LGTM, thanks """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702584651
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
ikerexxe commented: """ I've checked the new tags and they don't seem to print any strange characters on github. So, they are fine from my side. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702588418
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
alexey-tikhonov commented: """ Overall LGTM. I only added few minor comments inline. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702596579
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: synchronized
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Addressed Alexey's comments. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702664242
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
alexey-tikhonov commented: """ Thank you. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-702666126
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: +Accepted
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: -Waiting for review
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Thank you. I'm setting the accepted label. I will push this patch next Monday if there will not be further comments. """
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-703496874
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: +Ready to push
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
pbrezina commented: """ Pushed PR: https://github.com/SSSD/sssd/pull/5257
* `master` * ad6944118f5feddbc68bb2607c6beea6632e7387 - git-template: add tags to help with release notes automation
"""
See the full comment at https://github.com/SSSD/sssd/pull/5257#issuecomment-707019831
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: +Pushed
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: -Ready to push
URL: https://github.com/SSSD/sssd/pull/5257 Author: pbrezina Title: #5257: git-template: add tags to help with release notes automation Action: closed
To pull the PR as Git branch: git remote add ghsssd https://github.com/SSSD/sssd git fetch ghsssd pull/5257/head:pr5257 git checkout pr5257
URL: https://github.com/SSSD/sssd/pull/5257 Title: #5257: git-template: add tags to help with release notes automation
Label: -Accepted
sssd-devel@lists.fedorahosted.org
-
alexey-tikhonov -
elkoniu
-
ikerexxe
-
pbrezina
-
sumit-bose
-
thalman