• Itai Admi

    Itai Admi

    9 months ago
    I think we all agreed that the current way we handle the changelog is a mess (more details on the current process below). My suggestion is simple, revert it to the way it was before. The releaser looks at the completed PRs and gathers a list of meaningful changes. Yes, it means that the responsibility returns to the releaser. It also means that our commit messages need to describe the change better, which I think we’ve improved at. In case of ambiguity, we can always ask for more details and/or edit the release notes later. Current Process Author and reviewer are responsible for adding a line when required to the changelog. What normally happens is that they forget, only to open an additional PR to add that line when/if they remember later. When releasing the changelog becomes the release notes as is without further actions needed from the releaser.
  • Guy Hardonag

    Guy Hardonag

    9 months ago
    I do agree it’s better than what we have today, but we tried using the
    changelog
    file because the release task included going over all the commits and talking with all the committers in order to understand what should go in the changelog. Maybe we should give something else a shot before going back.
  • Ariel Shaqed (Scolnicov)

    Ariel Shaqed (Scolnicov)

    9 months ago
    👍🏽 for what Guy said. Going over all commits requires good enough log messages. To go there we should start by improving titles of our PRs, as well as better descriptions.
  • Karen

    Karen

    9 months ago
    In general terms a self-service is a pretty good approach. It would mean that every contributor should take care of their contributions and transfer its description to upcoming releases' changelog in a way that is readable and understandable by 3rd parties / uninvolved people. There still might be a process / task just before a release when some dedicated person goes and checks if the changelog looks appropriate. No idea how realistic it would be to introduce these kind of changes. Just sharing here some general thoughts on it.
  • Here is the changelog of the latest release. Just as an example.
    - Airflow hook nil assignment fix
    - Bug fix: pyramid store file fallback when destination already exist in cache
    - Bugfix/2400 change error message repo with new storage type
    - Fix UI base branch changes compare branch
    - UI - keep path when changing reference in object view
    - Using simple mime library that gives a consistent content-type on all platforms
    For one thing it would be really nice to be able to clearly distinguish what is a bug fix and what is a new feature. So, in bug fixes it would be nice to have the word "fix" / "fixed" etc. Everything else would be seen as a new feature.
  • Itai Admi

    Itai Admi

    9 months ago
    @Guy Hardonag I am open to other suggestions that will reduce the current friction, but came up with none other than the previous..
  • Guy Hardonag

    Guy Hardonag

    9 months ago
    Found this, looks like it could be useful.
  • we could start with two labels
    include-in-changelog
    exclude-from-changelog
    and enforce using at least one of them in the PR
  • That way: • We reduce the number of PRs we need to go over when releasing • There is a higher chance the committer would remember to add a comment or edit the title accordingly (believe that could be enforced as well)
  • Itai Admi

    Itai Admi

    9 months ago
    I like it! I’m willing to try it out
  • Ariel Shaqed (Scolnicov)

    Ariel Shaqed (Scolnicov)

    9 months ago
    Me too! Give the responsibility to the humans 👩🏽👨🏽, and use a bot 🤖 to ensure compliance.
  • Karen

    Karen

    9 months ago
    On a separate note. Still thinking about a new feature / bug fix distinguishing in cases when it's not clear from a PR's title. One could look into an issue, which the PR in question is closing. An issue would usually have a "bug" or a different lable, which could be used to deduce if it's a bug fix or an enhancement...
  • Tal Sofer

    Tal Sofer

    9 months ago
    @Karen we have a bug label and we usually remember to use it. @Guy Hardonag how about to use the labels you suggested to auto-generate the release notes, and to distinguish between bugs and features? I guess there is a way to do that. • Get all the commits done since the previous release (like we do today) • Keep only commits linked to PRs labeled with
    include-in-changelog
    • Check if the issue closed by the PR has a
    bug
    label
  • Guy Hardonag

    Guy Hardonag

    9 months ago
    Sounds great, We remember to use the bug label on the issue, it would be more convenient though if it would appear on the PR. Your suggestion sure is a good place to start with and see how it goes. later on we could break the
    include-in-changelog
    into more specific labels (such as
    bug
    ,
    enhancement
    ).
  • Barak Amar

    Barak Amar

    9 months ago
    Late to this discussion but I don't think that labeling all the PRs in order to make a change-log will be a good practice. If we think a PR is customer facing and we like to have such label and in the review is good. But Enforcement by choosing one of the labels - it will just make me automate a label on my every new PR. We can use a prefix as part of the PR title to filter out non-customer facing changes and let goreleaser generate the chanagelog. All the above are relevant to the PR but it will not solve the actual problem the CHANGELOG doesn't hold just the PR description. It hold the bug or feature description associated to the PR. So this job is not removed if we don't edit the file itself and the problem is that the file is always updated after the change or get conflicts all the time, if we update it during our development. If we do quick releases and goreleaser filter out the changes which are not customer facing - I don't think it is a problem to update the github or the changelog at that point in time and release.
  • Itai Admi

    Itai Admi

    9 months ago
    For future reference, the release process proposal is in this PR.
    it will just make me automate a label on my every new PR. Which is the exact opposite of what we’re trying to achieve. Why would someone maliciously do that? The entire purpose is to flag if changelog should reflect the changes in the PR.
    We can use a prefix as part of the PR title to filter out non-customer facing changes and let goreleaser generate the chanagelog Why is a prefix better than a tag? We need some automation and tag is cleaner.
    the CHANGELOG doesn’t hold just the PR description. It hold the bug or feature description associated to the PR. This is exactly where we need to improve. The description should include the new feature description, the bug fix and not implementation details. This is exactly what the changelog currently holds.
    that the file is always updated after the change or get conflicts all the time, if we update it during our development. Changelog updates once before release, now manually, later on we can add automation.
  • Barak Amar

    Barak Amar

    9 months ago
    My comment about using the label by default is not to be malicious, is usually what happens when a system try to add more and more mandatory fields. I agree this is something we need to improve. It comes down to using labels as part of requirement of creating PRs in our system. It is one way to educate developers to add label (not talking just about our team) as part of a change or look at the commit log and see that there are conventions of how to title a PR. I'm all for experimenting and will use the labels - but I think PR title conventions are easier to teach people outside the company that labels.
  • Itai Admi

    Itai Admi

    9 months ago
    But that’s the things, anything that requires human intervention is prune to errors. If you’re blocked because you didn’t tag your PR appropriately, it requires you to first think about the changelog (and then paying attention to the PR title), then add the tag. Rerunning it again is less than 30 seconds since the action completes fast.
  • Barak Amar

    Barak Amar

    9 months ago
    Giving it a try - just wonder how all other open source project address this one. I don't remember in any of my PRs that I had to add a label to submit one.
  • For the record I like the one way - label something that needs to be part of the changelog
  • The other one that requires me to enable to have a valid pr is the one that bothers me. Understand it is part of the process and not sure I like how we educate.
  • Ariel Shaqed (Scolnicov)

    Ariel Shaqed (Scolnicov)

    9 months ago
    I don't think outsiders are allowed to touch labels, not even for their own PRs and issues. (But I Could Be Wrong ™️ )
  • Itai Admi

    Itai Admi

    9 months ago
    I’m open to other suggestions, but prefixing the PR descriptions will be forgotten just as adding a line to the changelog
  • Barak Amar

    Barak Amar

    9 months ago
    Searched github - sure you also found there are projects that included "pr/no-changelog" and others that use only "impact/changelog"
  • Don't have better idea for now - so lets continue with our last decision