[ENH] Use and document towncrier for creating and maintaining changelogs #213

Merged

synchon merged 15 commits from update/towncrier into main 2023-03-30 09:19:42 +00:00

Conversation 12 Commits 15 Files changed 43 +342 -262

synchon commented 2023-03-28 17:59:24 +00:00 (Migrated from github.com)

Copy link

• fix #(issue number)
• description of feature/fix
• tests added/passed
• add an entry for the latest changes

This PR adds support for towncrier to maintain changelogs.

* [ ] fix #(issue number) * [x] description of feature/fix * [x] tests added/passed * [x] add an entry for the latest changes This PR adds support for `towncrier` to maintain changelogs.

codecov[bot] commented 2023-03-28 18:05:09 +00:00 (Migrated from github.com)

Copy link

Codecov Report

Merging #213 (fa6ef60) into main (8d04432) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #213   +/-   ##
=======================================
  Coverage   93.33%   93.33%           
=======================================
  Files          80       80           
  Lines        3435     3435           
  Branches      644      644           
=======================================
  Hits         3206     3206           
  Misses        151      151           
  Partials       78       78           

Flag	Coverage Δ
docs	100.00% <ø> (ø)
junifer	93.32% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

## [Codecov](https://codecov.io/gh/juaml/junifer/pull/213?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=juaml) Report > Merging [#213](https://codecov.io/gh/juaml/junifer/pull/213?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=juaml) (fa6ef60) into [main](https://codecov.io/gh/juaml/junifer/commit/8d04432faeb43bac5d815ebc03923f8a58102347?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=juaml) (8d04432) will **not change** coverage. > The diff coverage is `n/a`. [](https://codecov.io/gh/juaml/junifer/pull/213?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=juaml) ```diff @@ Coverage Diff @@ ## main #213 +/- ## ======================================= Coverage 93.33% 93.33% ======================================= Files 80 80 Lines 3435 3435 Branches 644 644 ======================================= Hits 3206 3206 Misses 151 151 Partials 78 78 ``` | Flag | Coverage Δ | | |---|---|---| | docs | `100.00% <ø> (ø)` | | | junifer | `93.32% <ø> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=juaml#carryforward-flags-in-the-pull-request-comment) to find out more.

fraimondo commented 2023-03-29 07:25:20 +00:00 (Migrated from github.com)

Copy link

We are missing some things:

1. make local should build the docs, including the latest news fragments. This is also used in the pr-preview.
2. As a consequence of 1, towncrier should be a dependency for docs
3. make html should also build the latest docs, including the news fragment of the "main" branch.

Solution 1) We can, of course, call towncrier build --keep to update whats_new.rst before doing the local and html. However, this will modify the whats_new.rst file, and this file will be a modified one for git.

Solution 2) We can have a towncrier_dev.toml that instead writes to dev_whats_new.rst, but then we need to deal with this file when it does not exist (e.g. on release)

Solution 3) Before make local and make html we create a copy of whats_new.rst. We then build the docs as in solution 1. After, we restore the original version of whats_new.rst.

@synchon: what's your take on this one?

We are missing some things: 1) `make local` should build the docs, including the latest news fragments. This is also used in the pr-preview. 2) As a consequence of 1, `towncrier` should be a dependency for `docs` 3) `make html` should also build the latest docs, including the news fragment of the "main" branch. Solution 1) We can, of course, call `towncrier build --keep` to update `whats_new.rst` before doing the `local` and `html`. However, this will modify the `whats_new.rst` file, and this file will be a modified one for git. Solution 2) We can have a `towncrier_dev.toml` that instead writes to `dev_whats_new.rst`, but then we need to deal with this file when it does not exist (e.g. on release) Solution 3) Before `make local` and `make html` we create a copy of `whats_new.rst`. We then build the docs as in solution 1. After, we restore the original version of `whats_new.rst`. @synchon: what's your take on this one?

synchon commented 2023-03-29 10:08:06 +00:00 (Migrated from github.com)

Copy link

We are missing some things:

1. make local should build the docs, including the latest news fragments. This is also used in the pr-preview.
2. As a consequence of 1, towncrier should be a dependency for docs
3. make html should also build the latest docs, including the news fragment of the "main" branch.

Solution 1) We can, of course, call towncrier build --keep to update whats_new.rst before doing the local and html. However, this will modify the whats_new.rst file, and this file will be a modified one for git.

Solution 2) We can have a towncrier_dev.toml that instead writes to dev_whats_new.rst, but then we need to deal with this file when it does not exist (e.g. on release)

Solution 3) Before make local and make html we create a copy of whats_new.rst. We then build the docs as in solution 1. After, we restore the original version of whats_new.rst.

@synchon: what's your take on this one?

My take would be:

1. PR-preview: Run the towncrier with --yes and --keep (or not) so it runs without prompt and then build the docs. This would make a whats_new.rst staged for commit but we don't bother as long as it builds ok as it's preview.
2. Pre-releases (non-release PRs merged to main): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to whats_new.rst.
3. Release: We will anyway create a new PR and check everything manually before making a release.

> We are missing some things: > > 1. `make local` should build the docs, including the latest news fragments. This is also used in the pr-preview. > 2. As a consequence of 1, `towncrier` should be a dependency for `docs` > 3. `make html` should also build the latest docs, including the news fragment of the "main" branch. > > Solution 1) We can, of course, call `towncrier build --keep` to update `whats_new.rst` before doing the `local` and `html`. However, this will modify the `whats_new.rst` file, and this file will be a modified one for git. > > Solution 2) We can have a `towncrier_dev.toml` that instead writes to `dev_whats_new.rst`, but then we need to deal with this file when it does not exist (e.g. on release) > > Solution 3) Before `make local` and `make html` we create a copy of `whats_new.rst`. We then build the docs as in solution 1. After, we restore the original version of `whats_new.rst`. > > @synchon: what's your take on this one? My take would be: 1. PR-preview: Run the `towncrier` with `--yes` and `--keep` (or not) so it runs without prompt and then build the docs. This would make a `whats_new.rst` staged for commit but we don't bother as long as it builds ok as it's preview. 2. Pre-releases (non-release PRs merged to `main`): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to `whats_new.rst`. 3. Release: We will anyway create a new PR and check everything manually before making a release.

fraimondo commented 2023-03-29 10:17:29 +00:00 (Migrated from github.com)

Copy link

We are missing some things:

1. make local should build the docs, including the latest news fragments. This is also used in the pr-preview.
2. As a consequence of 1, towncrier should be a dependency for docs
3. make html should also build the latest docs, including the news fragment of the "main" branch.

Solution 1) We can, of course, call towncrier build --keep to update whats_new.rst before doing the local and html. However, this will modify the whats_new.rst file, and this file will be a modified one for git.
Solution 2) We can have a towncrier_dev.toml that instead writes to dev_whats_new.rst, but then we need to deal with this file when it does not exist (e.g. on release)
Solution 3) Before make local and make html we create a copy of whats_new.rst. We then build the docs as in solution 1. After, we restore the original version of whats_new.rst.
@synchon: what's your take on this one?

My take would be:

1. PR-preview: Run the towncrier with --yes and --keep (or not) so it runs without prompt and then build the docs. This would make a whats_new.rst staged for commit but we don't bother as long as it builds ok as it's preview.
2. Pre-releases (non-release PRs merged to main): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to whats_new.rst.
3. Release: We will anyway create a new PR and check everything manually before making a release.

First reply:

1. PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on make local
2. Pre-releases. The repo should not change. The docs should. Also, it relies on make html
3. Release, not an issue, we do it manually

So both of the issues will be solved if the Makefile accounts for this.

> > We are missing some things: > > > > 1. `make local` should build the docs, including the latest news fragments. This is also used in the pr-preview. > > 2. As a consequence of 1, `towncrier` should be a dependency for `docs` > > 3. `make html` should also build the latest docs, including the news fragment of the "main" branch. > > > > Solution 1) We can, of course, call `towncrier build --keep` to update `whats_new.rst` before doing the `local` and `html`. However, this will modify the `whats_new.rst` file, and this file will be a modified one for git. > > Solution 2) We can have a `towncrier_dev.toml` that instead writes to `dev_whats_new.rst`, but then we need to deal with this file when it does not exist (e.g. on release) > > Solution 3) Before `make local` and `make html` we create a copy of `whats_new.rst`. We then build the docs as in solution 1. After, we restore the original version of `whats_new.rst`. > > @synchon: what's your take on this one? > > My take would be: > > 1. PR-preview: Run the `towncrier` with `--yes` and `--keep` (or not) so it runs without prompt and then build the docs. This would make a `whats_new.rst` staged for commit but we don't bother as long as it builds ok as it's preview. > 2. Pre-releases (non-release PRs merged to `main`): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to `whats_new.rst`. > 3. Release: We will anyway create a new PR and check everything manually before making a release. First reply: 1) PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on `make local` 2) Pre-releases. The repo should not change. The docs should. Also, it relies on `make html` 3) Release, not an issue, we do it manually So both of the issues will be solved if the Makefile accounts for this.

synchon commented 2023-03-29 10:51:50 +00:00 (Migrated from github.com)

Copy link

We are missing some things:

1. make local should build the docs, including the latest news fragments. This is also used in the pr-preview.
2. As a consequence of 1, towncrier should be a dependency for docs
3. make html should also build the latest docs, including the news fragment of the "main" branch.

Solution 1) We can, of course, call towncrier build --keep to update whats_new.rst before doing the local and html. However, this will modify the whats_new.rst file, and this file will be a modified one for git.
Solution 2) We can have a towncrier_dev.toml that instead writes to dev_whats_new.rst, but then we need to deal with this file when it does not exist (e.g. on release)
Solution 3) Before make local and make html we create a copy of whats_new.rst. We then build the docs as in solution 1. After, we restore the original version of whats_new.rst.
@synchon: what's your take on this one?

My take would be:

1. PR-preview: Run the towncrier with --yes and --keep (or not) so it runs without prompt and then build the docs. This would make a whats_new.rst staged for commit but we don't bother as long as it builds ok as it's preview.
2. Pre-releases (non-release PRs merged to main): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to whats_new.rst.
3. Release: We will anyway create a new PR and check everything manually before making a release.

First reply:

1. PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on make local
2. Pre-releases. The repo should not change. The docs should. Also, it relies on make html
3. Release, not an issue, we do it manually

So both of the issues will be solved if the Makefile accounts for this.

1. When the user builds the documentation, towncrier doesn't need to be called so it wouldn't stage anything in git.
2. What if we don't change the docs as we would already have the news fragmnets we need to make the complete doc when making a release. (Building non-release version docs would have been better if we had a dev branch which could in turn have a what_new_dev.rst but that's a different case.)

> > > We are missing some things: > > > > > > 1. `make local` should build the docs, including the latest news fragments. This is also used in the pr-preview. > > > 2. As a consequence of 1, `towncrier` should be a dependency for `docs` > > > 3. `make html` should also build the latest docs, including the news fragment of the "main" branch. > > > > > > Solution 1) We can, of course, call `towncrier build --keep` to update `whats_new.rst` before doing the `local` and `html`. However, this will modify the `whats_new.rst` file, and this file will be a modified one for git. > > > Solution 2) We can have a `towncrier_dev.toml` that instead writes to `dev_whats_new.rst`, but then we need to deal with this file when it does not exist (e.g. on release) > > > Solution 3) Before `make local` and `make html` we create a copy of `whats_new.rst`. We then build the docs as in solution 1. After, we restore the original version of `whats_new.rst`. > > > @synchon: what's your take on this one? > > > > > > My take would be: > > > > 1. PR-preview: Run the `towncrier` with `--yes` and `--keep` (or not) so it runs without prompt and then build the docs. This would make a `whats_new.rst` staged for commit but we don't bother as long as it builds ok as it's preview. > > 2. Pre-releases (non-release PRs merged to `main`): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to `whats_new.rst`. > > 3. Release: We will anyway create a new PR and check everything manually before making a release. > > First reply: > > 1. PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on `make local` > 2. Pre-releases. The repo should not change. The docs should. Also, it relies on `make html` > 3. Release, not an issue, we do it manually > > So both of the issues will be solved if the Makefile accounts for this. 1. When the user builds the documentation, `towncrier` doesn't need to be called so it wouldn't stage anything in git. 2. What if we don't change the docs as we would already have the news fragmnets we need to make the complete doc when making a release. (Building non-release version docs would have been better if we had a `dev` branch which could in turn have a `what_new_dev.rst` but that's a different case.)

fraimondo commented 2023-03-29 11:09:37 +00:00 (Migrated from github.com)

Copy link

We are missing some things:

1. make local should build the docs, including the latest news fragments. This is also used in the pr-preview.
2. As a consequence of 1, towncrier should be a dependency for docs
3. make html should also build the latest docs, including the news fragment of the "main" branch.

Solution 1) We can, of course, call towncrier build --keep to update whats_new.rst before doing the local and html. However, this will modify the whats_new.rst file, and this file will be a modified one for git.
Solution 2) We can have a towncrier_dev.toml that instead writes to dev_whats_new.rst, but then we need to deal with this file when it does not exist (e.g. on release)
Solution 3) Before make local and make html we create a copy of whats_new.rst. We then build the docs as in solution 1. After, we restore the original version of whats_new.rst.
@synchon: what's your take on this one?

My take would be:

1. PR-preview: Run the towncrier with --yes and --keep (or not) so it runs without prompt and then build the docs. This would make a whats_new.rst staged for commit but we don't bother as long as it builds ok as it's preview.
2. Pre-releases (non-release PRs merged to main): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to whats_new.rst.
3. Release: We will anyway create a new PR and check everything manually before making a release.

First reply:

1. PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on make local
2. Pre-releases. The repo should not change. The docs should. Also, it relies on make html
3. Release, not an issue, we do it manually

So both of the issues will be solved if the Makefile accounts for this.

1. When the user builds the documentation, towncrier doesn't need to be called so it wouldn't stage anything in git.

Yes they need to do it. Otherwise it would not be the same doc as in the pr-preview / main branch. The dev should be able to build the same docs locally.

2. What if we don't change the docs as we would already have the news fragmnets we need to make the complete doc when making a release. (Building non-release version docs would have been better if we had a dev branch which could in turn have a what_new_dev.rst but that's a different case.)

Pre-release docs (as well as pr-preview) should include the changes in the DEV version. like we have now:

The point is that the whats_new_rst file is only commited to git on the release process. But it needs to be modified for:
make local, make html, which will affect PR-preview and pre-release docs repectively.

> > > > We are missing some things: > > > > > > > > 1. `make local` should build the docs, including the latest news fragments. This is also used in the pr-preview. > > > > 2. As a consequence of 1, `towncrier` should be a dependency for `docs` > > > > 3. `make html` should also build the latest docs, including the news fragment of the "main" branch. > > > > > > > > Solution 1) We can, of course, call `towncrier build --keep` to update `whats_new.rst` before doing the `local` and `html`. However, this will modify the `whats_new.rst` file, and this file will be a modified one for git. > > > > Solution 2) We can have a `towncrier_dev.toml` that instead writes to `dev_whats_new.rst`, but then we need to deal with this file when it does not exist (e.g. on release) > > > > Solution 3) Before `make local` and `make html` we create a copy of `whats_new.rst`. We then build the docs as in solution 1. After, we restore the original version of `whats_new.rst`. > > > > @synchon: what's your take on this one? > > > > > > > > > My take would be: > > > > > > 1. PR-preview: Run the `towncrier` with `--yes` and `--keep` (or not) so it runs without prompt and then build the docs. This would make a `whats_new.rst` staged for commit but we don't bother as long as it builds ok as it's preview. > > > 2. Pre-releases (non-release PRs merged to `main`): Although we update the changelog now, I'm not sure if it makes sense to update the changelog with every pre-release changes. So, I wouldn't make any changes to `whats_new.rst`. > > > 3. Release: We will anyway create a new PR and check everything manually before making a release. > > > > > > First reply: > > > > 1. PR-preview is not an issue. The problem is the user building the documentation. This will stage changes in git. I don't want that to happen. PR-preview relies on `make local` > > 2. Pre-releases. The repo should not change. The docs should. Also, it relies on `make html` > > 3. Release, not an issue, we do it manually > > > > So both of the issues will be solved if the Makefile accounts for this. > > 1. When the user builds the documentation, `towncrier` doesn't need to be called so it wouldn't stage anything in git. Yes they need to do it. Otherwise it would not be the same doc as in the pr-preview / main branch. The dev should be able to build the same docs locally. > 2. What if we don't change the docs as we would already have the news fragmnets we need to make the complete doc when making a release. (Building non-release version docs would have been better if we had a `dev` branch which could in turn have a `what_new_dev.rst` but that's a different case.) Pre-release docs (as well as pr-preview) should include the changes in the DEV version. like we have now:  The point is that the `whats_new_rst` file is only commited to git on the release process. But it needs to be modified for: `make local`, `make html`, which will affect PR-preview and pre-release docs repectively.

fraimondo commented 2023-03-29 11:10:59 +00:00 (Migrated from github.com)

Copy link

In short, behaviour should not change with respect to what we have now. Only implementation.

In short, behaviour should not change with respect to what we have now. Only implementation.

synchon commented 2023-03-29 12:51:28 +00:00 (Migrated from github.com)

Copy link

In that case I would adapt your solutions like this:

• Make a towncrier_dev.toml with the difference being in `filename = "docs/whats_new_dev.rst"
• Include towncrier build --config towncrier_dev.toml --keep in Makefile before sphinx and ask user to commit that as well.
• Make a new file changelog.rst and include whats_new.rst and whats_new_dev.rst in there as two sections in it.

In that case I would adapt your solutions like this: - Make a `towncrier_dev.toml` with the difference being in `filename = "docs/whats_new_dev.rst" - Include `towncrier build --config towncrier_dev.toml --keep` in Makefile before `sphinx` and ask user to commit that as well. - Make a new file `changelog.rst` and include `whats_new.rst` and `whats_new_dev.rst` in there as two sections in it.

fraimondo commented 2023-03-29 13:22:54 +00:00 (Migrated from github.com)

Copy link

In that case I would adapt your solutions like this:

• Make a towncrier_dev.toml with the difference being in `filename = "docs/whats_new_dev.rst"
• Include towncrier build --config towncrier_dev.toml --keep in Makefile before sphinx and ask user to commit that as well.
• Make a new file changelog.rst and include whats_new.rst and whats_new_dev.rst in there as two sections in it.

Why commit? There's nothing to commit. The ".dev" changes of the whats_new should be re-created every time without commit.

This also does not work, as sphinx complains that whats_new_dev.rst does not exist (on releases). If we add an empty file, then we are in the same issue as before (git changes).

Solution: make local and make html should:

1. towncrier build --keep
2. make the respective target
3. revert whats_new.rst to how it was before 1): git stash -- docs/whats_new.rst

> In that case I would adapt your solutions like this: > > * Make a `towncrier_dev.toml` with the difference being in `filename = "docs/whats_new_dev.rst" > * Include `towncrier build --config towncrier_dev.toml --keep` in Makefile before `sphinx` and ask user to commit that as well. > * Make a new file `changelog.rst` and include `whats_new.rst` and `whats_new_dev.rst` in there as two sections in it. Why `commit`? There's nothing to commit. The ".dev" changes of the whats_new should be re-created every time without commit. This also does not work, as sphinx complains that `whats_new_dev.rst` does not exist (on releases). If we add an empty file, then we are in the same issue as before (git changes). Solution: `make local` and `make html` should: 1) towncrier build --keep 2) make the respective target 3) revert `whats_new.rst` to how it was before 1): `git stash -- docs/whats_new.rst`

github-actions[bot] commented 2023-03-29 14:15:42 +00:00 (Migrated from github.com)

Copy link

PR Preview Action v1.3.0
Preview removed because the pull request was closed.
2023-03-30 09:23 UTC

[PR Preview Action](https://github.com/rossjrw/pr-preview-action) v1.3.0 :---: Preview removed because the pull request was closed. 2023-03-30 09:23 UTC <!-- Sticky Pull Request Commentpr-preview -->

fraimondo commented 2023-03-29 20:36:56 +00:00 (Migrated from github.com)

Copy link

needs this in the CI for docs and docs preview:
Otherwise it does not install the full package with history, but only the last commit.

      with:
        fetch-depth: 0
        submodules: true

needs this in the CI for docs and docs preview: Otherwise it does not install the full package with history, but only the last commit. ``` with: fetch-depth: 0 submodules: true ```

fraimondo (Migrated from github.com) reviewed 2023-03-30 08:20:26 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

CRITICAL

High Priority Issue

  

Stale

  

WIP

Work in progress

  

bug

Something isn't working

  

concept

Design/Implementation concepts

  

coordinate

Issues or pull requests related to coordinates (ROIs)

  

dataset

Issues or pull requests related to datagrabbers or datasets

  

dependencies

Pull requests that update a dependency file

  

documentation

Improvements or additions to documentation

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

github_actions

Pull requests that update GitHub Actions code

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

maintenance

Issues or pull requests related to maintenance

  

maps

Issues or pull requests related to maps (probabilistic atlases)

  

marker

Issues or pull requests related to markers

  

mask

Issues or pull requests related to masks

  

on hold

Issue waiting on other issue(s)

  

parcellation

Issues or pull requests related to parcellations (deterministic atlases)

  

preprocess

Issues or pull requests related to preprocessors

  

question

Further information is requested

  

ready

Pull request is ready for review and merge

  

storage

Issues or pull requests related to marker storage or retrieval

  

template-space

Issues or pull requests related to template spaces

  

triage

New issues waiting to be reviewed

  

wontfix

This will not be worked on

No labels

CRITICAL

Stale

WIP

bug

concept

coordinate

dataset

dependencies

documentation

duplicate

enhancement

github_actions

good first issue

help wanted

invalid

maintenance

maps

marker

mask

on hold

parcellation

preprocess

question

ready

storage

template-space

triage

wontfix

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

juaml/junifer!213

No description provided.