@atztogo , @lan496 Can you help with labeling some of the past issues, especially the Breaking changes that triggered v2 major release?

Note:

• breaking-changes are changes that make it incompatible with a previous version, including removing things that were marked deprecated
• deprecation are changes that will be removed later on, but people can still use it currently
• If necessary, edit the titles so it makes more sense in the release notes. The release notes are drafts, we still need to manually review them and add minor notes, so don't overdo it.
• !! Only PRs are counted !!

Also there are a few release drafts if you can review a bit. Just delete unnecessary PRs and add a Main Changes if necessary. (The releases were auto generated, but there was not a good .github/release.yaml to format it nicely, but in principles that is what it would look like)

Codecov Report

Patch and project coverage have no change.

Comparison is base (0866e94) 85.69% compared to head (9446db6) 85.69%.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@           Coverage Diff            @@
##           develop     #254   +/-   ##
========================================
  Coverage    85.69%   85.69%           
========================================
  Files           23       23           
  Lines         6069     6069           
========================================
  Hits          5201     5201           
  Misses         868      868           

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

Note: I would like to add body_path which basically means we can add the text there instead of manually writing the changelog message. Hopefully it just diffs against the last release, but I don't know how it works.

Question: Where to link it to? changelog file makes most sense so people can just add small messages there. But it is currently used. Could we reset it and point it to the version of previous commit for the old changelog?

Because we write the release note at ./doc/releases.md currently, maybe this file is appropriate.

Could we reset it and point it to the version of previous commit for the old changelog?

I don't know why we need to reset it. Can you explain a little more?

Sure, this partially dependent on how softprops/action-gh-release. If it automatically diffs the last tag and appends the diff onto it, then we could use it as is. The issue is a) what happens at the initial setup (it's a draft so I guess it's not much of a concern to manually do it), b) it becomes confusing when there are two distinct differently formatted sections

But if the action simply takes all the content, we would need a simple script to generate it according to the last tag/version. Looking at the examples again, I think it might be this case.

As for doc/releases.md, unfortunately that file is not formatted to be easily read so we have to make a little design decision:

• Do we only include full release "Main Changes" notes there, i.e. not PRs and not rc releases?
  • In this case we extract the body and add it to the top of the auto generated release notes
  • Downside, we cannot steadily build up the notes without immediately deploying them to latest documentation
  • Adding the date of the future release would be tricky
• Do we use another file like changelog.md
  • Easier to maintain as we develop
  • Unclear how do we synchronize the doc/releases.md. We could have it to insert and format the content from changelog.md to doc/releases.md, but how do we trigger it?
    • If we do it by tag, we need to create a new commit with those changes, but at that point the tag does not point to the right commit.
    • A possible solution is to always automatically generate from a jinja template doc/releases.md, and make it generate on RTD side depending on a) it is latest (generate w/ last stable release content), b) it is version tag (generate w/ current content), c) it is rc tag (not sure), d) it is PR (always generate current content). Also easier to use a changelog.yaml in this case
  • Confusing if we have both changelog.md and changelog file

@LecrisUT Thanks for your detail explanation.
Considering Spglib's slow release cycles, I think it would be enough to focus solely on introducing action-gh-release, without concerning ourselves with automating the writing of release notes at this time.

Previous changelogs

The issue is a) what happens at the initial setup (it's a draft so I guess it's not much of a concern to manually do it), b) it becomes confusing when there are two distinct differently formatted sections

I think these issues are not so serious that we do not need to reset or format the previous changelogs.
Of course, it would be preferable to adopt a consistent format for all new versions going forward.

Location of changelog files

./ChangeLog is changelogs for previous major versions spglib<2.
Now we use ./doc/releases.md for new versions.
It will be less confusing to merge ./ChangeLog into ./doc/releases.md.
Although the current changelog file is located under ./doc, we can move it to the root, which would be more accessible.

Content of changelogs

Do we only include full release "Main Changes" notes there, i.e. not PRs and not rc releases?

I agree with this approach.
The downside does not seem to be so critical for now because we can simply see it in GitHub.
@atztogo What do you think about the format for changelogs?

Ok, I've opened #257 to discuss how we want to format the files. Otherwise, this PR is ready as it is.

I can't see overview of these works because works seem scattered into multiple PRs/issues and I don't understand some terminologies. @LecrisUT, could you summarize your direction?

You mean around all the merged/open PRs or the ones that depend on this? For the former we can discuss them in #239, I'll go over the ones that depend on these.

• Include an autoreleaser #254 (this) simply automates the release and creates a draft release (see release page of this repo) from the merged PRs
• Improve release documentaiton #257 depends on #254 softly. This one automates the release.md and the main text that will be in the release drafts, the latter of which why it depends on #254. It moves all of the text to a changelog.yaml so that it is shared for both release.md and the release drafts, and it can be written as we add features
• Doxygen documentation #259 does not really depend on #254. It uses the same versions of sphinx as in #257 and I did not rebase the other out. That one simplifies the documentation, moving it into the code

I learned the fact that there are really many tools.

To be honest, I am learning about them as it goes as well. I know about these from collaborating on random non-academic projects, and I reference them to see how they use them and what alternatives are more suited for this.

Already though this project has had a good start with pre-commit and sphinx that I have not seen adopted in academic projects, and I must thank you for having had that initiative. It pays off greatly in getting new contributors.

@LecrisUT, thank you very much!