Add: changelog-file.md to the Docs-for-Contributors-and-Maintainers section. #222

miguelalizo · 2024-04-08T18:56:27Z

Addresses Issue #215 - Describe what a changelog is in the documentation

…ap in the Docs for Contributors and Maintainers section. Update documentation/index.md to add changelog-file.md to the toctree.

miguelalizo · 2024-04-08T19:28:01Z

I think this addition is in a good state to be review. I tried to capture the information from the issue and maybe a bit more. Open to discussion if anything is missing or needs to be changed!

lwasser · 2024-04-09T20:54:11Z

@miguelalizo this page is great. Thank you for another wonderful PR.

Note: when we add new content to our pyOpenSci guidebook, we always have a community review period! I've left a bit of feedback. I also opened the pr up for community review. I gave folks a week to provide feedback. I will check back in next week and we will then get this merged!

miguelalizo · 2024-04-09T21:21:45Z

@lwasser Thanks for leaving some feedback! I'm having trouble finding where you left the feedback. Is it tied to this PR somwhere?

lwasser

i'm glad that you pinged me! i left a review and didn't actually submit it. all of the comments should be visible now - my mistake!

lwasser · 2024-04-09T20:35:46Z

documentation/repository-files/changelog-file.md

+
+[Keep a Changelog.md](https://keepachangelog.com/en/1.1.0/) is great, simple resource for understanding what a changelog is, how to create a good changelog, and includes some pointers of things to avoid in a changelog.
+
+```{admonition} Semantic Versioning


let's add a call out / link to this page on versioning your package that is in the guide (which also recommends semver!!!

https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-versions.html

Totally missed this page! Thanks for the pointer. Just added a callout in the admonition

lwasser · 2024-04-09T20:47:28Z

documentation/repository-files/changelog-file.md

+
+- **Contributor Recognition**: Acknowledgment of contributors who made significant contributions to the release, fostering a sense of community and appreciation for their efforts.
+
+## What does it look like?


I wonder if we want to add a short section regarding how maintainers use the changelog.
Something like (just an idea for language but feel free to adjust)

Often you will see a change log that documents a few things

Unreleased commits
at the top of the changelog, it's common to have an ## Unreleased section. This is where you can add new fixes, updates and features that have been added to the package since the last release.
This section might look something like this:

## Unreleased * Fix: Fixed a bug.... more here. (@github_username, #issuenumber) * Add: new feature to ...more here (@github_username, #issuenumber)

Below the unreleased section, there will be a section for each release. In these sections, you can organize new Fixes, Additions and update together.

## v1.0 ### Updates * Fix: Fixed a bug.... more here. (@github_username, #issuenumber) ### Additions * Add: new feature to ...more here (@github_username, #issuenumber) ### Deprecations ### Contributors to this release

When you are ready to make a new release, you can re-organize the list of unreleased elements into a section that is specific to that new release number.

The unreleased section then always lives at the top of the file. And as new features are added after release 1.x, they get added to that section.

This is great! I will add a section titled "How do maintainers use it?" right before the "What does it look like?" section. Also, your writeup is already very descriptive and I'm not sure there is more to add to it.

ok fantastic!! thank you!

lwasser · 2024-04-09T20:48:42Z

documentation/repository-files/changelog-file.md

+
+### Fixed
+
+- [PROJECTNAME-TTTT](http://tickets.projectname.com/browse/PROJECTNAME-TTTT)


I like this. i often just use a issue number on github. but i could see that maybe some projects might have a different type of issue tracker. we might want to default to github/gitlab aproach for this guide however and could have a breakout that talks about different ways to link to issue tracker tickets!

See comment

ucodery

This is a wonderful guide. Very motivating to the new project author I think!

documentation/repository-files/changelog-file.md

ucodery · 2024-04-09T21:39:39Z

documentation/repository-files/changelog-file.md

+
+[Keep a Changelog.md](https://keepachangelog.com/en/1.1.0/) is great, simple resource for understanding what a changelog is, how to create a good changelog, and includes some pointers of things to avoid in a changelog.
+
+```{admonition} Semantic Versioning


Versioning is a big topic, so much so that we have a guide for it! https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-versions.html

We should link there rather than try and define semver twice in this guide IMO. But a good tip could be that the version string of a release often makes "chapters" in a changelog.

Thanks for the callout @ucodery . @lwasser mentioned the same exact point in the feedback above and I just made sure to add a call-out rather than duplicating the effort.

ucodery · 2024-04-09T21:48:01Z

documentation/repository-files/changelog-file.md

+
+## What does it look like?
+
+```markdown


This is great, but I think real examples are sometimes easier to follow than ones entirely made up. We must have a project already that has a well-maintained changelog (@lwasser ?) that we can copy as an example? We could clip it for the code block and link to the repo for curious reader to dig deeper.

I think this is a great idea. Also, it does seem like the projects will benefit from this guide on changelogs since after going through almost all the projects on PyOpenSci, there is an clear trend of not having a standard for changelogs. Some projects have them as rst files, some projects have them as .txt file and many don't have a changeling at all!

I just added the changelog of Devicely as it is one of the few markdown versions that also follows semver and is based on keep a changelog. The format is not perfect however, since the with the 1.1.0, it seems the project authors stopped using the Added / Changed / Removed subheadings.

Please advice if we'd like to revert back to the template example as opposed to the real example from Devicely if needed.

i agree with you both - great suggestion. let's use the real world example rather than a made up one!! and i love that we are also highlighting one of our packages by doing this!

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

…nsistent use of CHANGELOG.md

miguelalizo · 2024-04-09T23:51:50Z

@lwasser @ucodery thanks for the feedback! I made some edits and left some comments in the reviews to try to clarify any doubts I had.

ucodery · 2024-04-10T16:49:27Z

documentation/repository-files/changelog-file.md

-```markdown
-# Change Log
-All notable changes to this project will be documented in this file.
+Often you will see a change log that documents a few things


Suggested change

Often you will see a change log that documents a few things

Often you will see a changelog that documents a few things

This sounds like the opener to a bulleted list. But I think the amount of detail that follows is too much for a list, can this be refactored into a full introduction sentence?

documentation/repository-files/changelog-file.md

ucodery · 2024-04-10T16:54:02Z

documentation/repository-files/changelog-file.md

+## Unreleased
+* Fix: Fixed a bug.... more here. (@github_username, #issuenumber)
+* Add: new feature to ...more here (@github_username, #issuenumber)
+Below the unreleased section, there will be a section for each release. In these sections, you can organize new Fixes, Additions and update together.


This sounds more like the guide and not something readers should copy into a CHANGELOG file.

I agree. I moved explanation out and cleaned up the section.

documentation/repository-files/changelog-file.md

ucodery · 2024-04-10T16:59:44Z

documentation/repository-files/changelog-file.md


-## [1.2.4] - 2017-03-15
+When you are ready to make a new release, you can re-organize the list of unreleased elements into a section that is specific to that new release number.


This makes the process of releasing a changelog sound complicated. I think if a maintainer follows the best practices described here making a release can be done by adding 2 lines

## Unreleased + + ## v5.12.0

ahhhh @ucodery this might be partially my fault.

this is what i'm used to seeing

or this

essentially you have a large flowing unreleased section. Then when you go to make a release, you organize into fixed, added, removed/ deprecated contributors.

However your suggest is also good and much simpler. i'm curious what you think? we could stick with the simpler version but add a small breakout on how the changelog might be reorganized for a release (as an option).

Any changelog is better than no changelog so i'm open to thoughts here :)

Both valid points! I think it's easier to just see an example of where my thoughts are on this rather than explaining it. I rewrote the section and took somewhat of a hybrid approach. Let me know what you think!

Okay, that makes more sense, thanks for the examples @lwasser!

documentation/repository-files/changelog-file.md

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

…arkdown blocks.

… section

ucodery

Awesome work!

lwasser

This looks great @miguelalizo many thanks! @ucodery thanks again for all of the review here!! let's merge!

tkoyama010 · 2024-08-09T14:38:30Z

@all-contributors please add @miguelalizo for doc

allcontributors · 2024-08-09T14:38:39Z

@tkoyama010

I've put up a pull request to add @miguelalizo! 🎉

miguelalizo added 4 commits April 8, 2024 11:52

Add changelog-file.md to documentation/repository-files/ to address g…

14359f3

…ap in the Docs for Contributors and Maintainers section. Update documentation/index.md to add changelog-file.md to the toctree.

Update changelog-file.md to remove typo/codespell.

98191d6

Update changelog-file.md to remove trailing whitespaces.

bb499cd

Update changelog-file.md to add a newline at EOF.

18b0cab

miguelalizo mentioned this pull request Apr 8, 2024

Describe what a changelog is in the documentation #215

Closed

lwasser added the 🚀 ready-for-review label Apr 9, 2024

lwasser requested changes Apr 9, 2024

View reviewed changes

ucodery reviewed Apr 9, 2024

View reviewed changes

miguelalizo and others added 8 commits April 9, 2024 15:47

Update changelog-file.md to add call-out to versioning page.

36a53fc

Update documentation/repository-files/changelog-file.md

8584f3e

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

Update documentation/repository-files/changelog-file.md

1108dc9

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

Update changelog-file.md to address reviewer feedback

d3000a9

Update changelog-file.md to consistely call out CHANGELOG.md

42300e1

Update python-package-distribution-files-sdists-wheel.md to ensure co…

0de62e3

…nsistent use of CHANGELOG.md

Update changelog example to use Devicely's real changelog

c617dc7

Add a 'How do developers use it' section to changelog-file.md

0edda99

ucodery reviewed Apr 10, 2024

View reviewed changes

miguelalizo and others added 7 commits April 10, 2024 19:28

Update documentation/repository-files/changelog-file.md

5048e97

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

Update documentation/repository-files/changelog-file.md

ae2d435

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

Update documentation/repository-files/changelog-file.md

bbaf612

Co-authored-by: Jeremy Paige <ucodery@gmail.com>

Merge branch 'pyOpenSci:main' into main

25961a9

Separate sections of how maintainers use a changelog into their own m…

0158d6f

…arkdown blocks.

Add third level heading for listed info in How do maintainers use it?…

4af3f10

… section

Change wording of change log to changelog

1e89674

ucodery approved these changes Apr 11, 2024

View reviewed changes

lwasser approved these changes Apr 15, 2024

View reviewed changes

lwasser merged commit 8ef5e93 into pyOpenSci:main Apr 15, 2024
4 checks passed

lwasser added the pycascades label May 29, 2024

allcontributors bot mentioned this pull request Aug 9, 2024

docs: add miguelalizo as a contributor for doc #365

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add: changelog-file.md to the Docs-for-Contributors-and-Maintainers section. #222

Add: changelog-file.md to the Docs-for-Contributors-and-Maintainers section. #222

miguelalizo commented Apr 8, 2024

miguelalizo commented Apr 8, 2024

lwasser commented Apr 9, 2024

miguelalizo commented Apr 9, 2024 •

edited

Loading

lwasser left a comment

lwasser Apr 9, 2024

miguelalizo Apr 9, 2024

lwasser Apr 9, 2024

miguelalizo Apr 9, 2024

lwasser Apr 10, 2024

lwasser Apr 9, 2024

miguelalizo Apr 9, 2024

ucodery left a comment

ucodery Apr 9, 2024

miguelalizo Apr 9, 2024

ucodery Apr 9, 2024

miguelalizo Apr 9, 2024

lwasser Apr 10, 2024

miguelalizo commented Apr 9, 2024

ucodery Apr 10, 2024

ucodery Apr 10, 2024

ucodery Apr 10, 2024

miguelalizo Apr 11, 2024

ucodery Apr 10, 2024

lwasser Apr 10, 2024

miguelalizo Apr 11, 2024

ucodery Apr 11, 2024

ucodery left a comment

lwasser left a comment

tkoyama010 commented Aug 9, 2024

allcontributors bot commented Aug 9, 2024


		[Keep a Changelog.md](https://keepachangelog.com/en/1.1.0/) is great, simple resource for understanding what a changelog is, how to create a good changelog, and includes some pointers of things to avoid in a changelog.

		```{admonition} Semantic Versioning


		- Contributor Recognition: Acknowledgment of contributors who made significant contributions to the release, fostering a sense of community and appreciation for their efforts.

		## What does it look like?


		### Fixed

		- [PROJECTNAME-TTTT](http://tickets.projectname.com/browse/PROJECTNAME-TTTT)

	Often you will see a change log that documents a few things
	Often you will see a changelog that documents a few things


		## [1.2.4] - 2017-03-15
		When you are ready to make a new release, you can re-organize the list of unreleased elements into a section that is specific to that new release number.

Add: changelog-file.md to the Docs-for-Contributors-and-Maintainers section. #222

Add: changelog-file.md to the Docs-for-Contributors-and-Maintainers section. #222

Conversation

miguelalizo commented Apr 8, 2024

miguelalizo commented Apr 8, 2024

lwasser commented Apr 9, 2024

miguelalizo commented Apr 9, 2024 • edited Loading

lwasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ucodery left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miguelalizo commented Apr 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ucodery left a comment

Choose a reason for hiding this comment

lwasser left a comment

Choose a reason for hiding this comment

tkoyama010 commented Aug 9, 2024

allcontributors bot commented Aug 9, 2024

miguelalizo commented Apr 9, 2024 •

edited

Loading