Skip to content

MNT Add section on new changelog entries to v1.6.rst #30135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 4 commits into from
Oct 24, 2024
Merged

MNT Add section on new changelog entries to v1.6.rst #30135

merged 4 commits into from
Oct 24, 2024

Conversation

lucyleeow
Copy link
Member

@lucyleeow lucyleeow commented Oct 23, 2024 •
edited
Loading

Reference Issues/PRs

Related to #30081 (comment)

What does this implement/fix? Explain your changes.

Adds minimal description of how to add new changelog entry file and points to full description README file.

cc @adrinjalali happy to change, to add more detail or less. (maybe I can list the change types?)

Any other comments?

@github-actions GitHub Actions
Copy link

github-actions bot commented Oct 23, 2024 •
edited
Loading

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

Generated for commit: e6150df. Link to the linter CI: here

adrinjalali
adrinjalali reviewed Oct 23, 2024
View reviewed changes
@lesteve
Copy link
Member

lesteve commented Oct 23, 2024

I prefer the initial proposal I have to admit: having a link (full URL) with maybe a short sentence for people that find having to open a link not quick enough.

I get the point about helping during the transition but I mean doc/whats_new/v1.6.rst should not become the main reference point for documenting how to add a changelog entry, https://github.com/scikit-learn/scikit-learn/blob/main/doc/whats_new/upcoming_changes/README.md should be the one.

@adrinjalali
Copy link
Member

My issue with putting this information only under the README is that it's hard to open it. We have a bunch of README files in the repo, which means CTRL+P README in my IDE doesn't easily find the right information. However, we don't have many 1.6.rst like files, so CTRL+P 1.6 immediately gives me the info. I'd like to have it very easy for people to find the info. And having to click and load a page is way too slow / too many steps.

@lesteve
Copy link
Member

lesteve commented Oct 23, 2024 •
edited
Loading

C-P what read seems to be OK enough ... (what is for whats_new) you can probably remove 1 or 2 characters if you really want. Yes I give you that it will still be longer than "1.6" ...

@adrinjalali
Copy link
Member

Sure, I could live with that. But the original suggestion mentions towncrier, which is really a technical detail that contributors don't care about. I'd be happy to see what you suggest as an alternative @lesteve

@lesteve
Copy link
Member

lesteve commented Oct 23, 2024

Something like this maybe?

..
  TODO DELETE WHEN 1.6.0 IS RELEASED
  Since October 2024, DO NOT add your changelog entry in this file.

  Instead, create a file named `<PR_number>.<type>.rst` in the relevant sub-folder in
  `doc/whats_new/upcoming_changes/`. For full details, see:
  https://github.com/scikit-learn/scikit-learn/blob/main/doc/whats_new/upcoming_changes/README.md

I used a URL hoping that it is easier to navigate to it.

lesteve
lesteve reviewed Oct 23, 2024
View reviewed changes
doc/whats_new/v1.6.rst Outdated
Comment on lines 17 to 36
.. DELETE WHEN 1.6.0 IS RELEASED
.. Changelog management has changed in v1.6.0.
.. To add your changelog, create a file under the right folder under
.. `doc/whats_new/upcoming_changes` with file format `<PULL REQUEST>.<TYPE>.rst`, where
.. `<PULL REQUEST>` is a pull request number, and `<TYPE>` is one of:
.. * `major-feature`
.. * `feature`
.. * `efficiency`
.. * `enhancement`
.. * `fix`
.. * `api`
.. Example of a changelog file:
.. - :class:`ensemble.ExtraTreesClassifier` and :class:`ensemble.ExtraTreesRegressor`
.. now supports missing values in the data matrix `X`. Missing-values are
.. handled by randomly moving all of the samples to the left, or right child
.. node as the tree is traversed.
.. By :user:`Adam Li <adam2392>`
.. See `doc/whats_new/upcoming_changes/README.md` for full details.
.. Note only pull requests that result in a change relevant to users require a
.. changelog entry (e.g., changes to private functions do not require a changelog).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#30135 (comment) was thumbed up by @adrinjalali so using this as a suggestion. @lucyleeow feel free to tweak it as you wish:

Suggested change
.. DELETE WHEN 1.6.0 IS RELEASED
.. Changelog management has changed in v1.6.0.
.. To add your changelog, create a file under the right folder under
.. `doc/whats_new/upcoming_changes` with file format `<PULL REQUEST>.<TYPE>.rst`, where
.. `<PULL REQUEST>` is a pull request number, and `<TYPE>` is one of:
.. * `major-feature`
.. * `feature`
.. * `efficiency`
.. * `enhancement`
.. * `fix`
.. * `api`
.. Example of a changelog file:
.. - :class:`ensemble.ExtraTreesClassifier` and :class:`ensemble.ExtraTreesRegressor`
.. now supports missing values in the data matrix `X`. Missing-values are
.. handled by randomly moving all of the samples to the left, or right child
.. node as the tree is traversed.
.. By :user:`Adam Li <adam2392>`
.. See `doc/whats_new/upcoming_changes/README.md` for full details.
.. Note only pull requests that result in a change relevant to users require a
.. changelog entry (e.g., changes to private functions do not require a changelog).
..
TODO DELETE WHEN 1.6.0 IS RELEASED
Since October 2024, DO NOT add your changelog entry in this file.
Instead, create a file named `<PR_number>.<type>.rst` in the relevant sub-folder in
`doc/whats_new/upcoming_changes/`. For full details, see:
https://github.com/scikit-learn/scikit-learn/blob/main/doc/whats_new/upcoming_changes/README.md

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since October 2024, DO NOT add your changelog entry in this file

This is perfect, tells the user exactly when the change happened and includes nothing they don't need to know, i don't know why I didn't say this 😅

Note the extra .. is because multiline comments do not seem to be able to contain blank lines

@adrinjalali adrinjalali merged commit 856ef1f into scikit-learn:main Oct 24, 2024
30 checks passed
@lucyleeow lucyleeow deleted the mnt_whats_new branch October 24, 2024 06:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@lesteve lesteve lesteve left review comments

@virchan virchan virchan left review comments

@adrinjalali adrinjalali adrinjalali approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@lucyleeow @lesteve @adrinjalali @virchan