Skip to content
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.

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

Add a changelog for tracking specification changes across versions #574

Merged
merged 5 commits into from
Dec 15, 2022

Conversation

kgryte
Copy link
Contributor

@kgryte kgryte commented Dec 15, 2022

This PR

  • adds a changelog for tracking specification changes across versions. As the v2022.12 revision is the second edition of the array API standard, the changelog only includes changes since the initial specification release.
  • distinguishes between "updates", "additions", and "errata". For the most part, errata are either typo fixes or areas of underspecification/need for clarification.
  • addresses part of Add a changelog #507

@kgryte kgryte added the Narrative Content Narrative documentation content. label Dec 15, 2022
@kgryte kgryte added this to the v2022 milestone Dec 15, 2022
Copy link
Member

@rgommers rgommers left a comment

Choose a reason for hiding this comment

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

Thanks @kgryte. This will be quite useful for implementers. A few comments here and inline, with as common theme aiming to be more explicit and easier on the reader. It's a little bit terse and not as easy to navigate as it could be.

It would be useful to add a short description at the top. Something like "This changelog is organized by specification version, noting all changes with respect to the previous version. Within the section for a specific version (e.g., v2022.12), separate sections are used for (a) changes to existing APIs and requirements, (b) new APIs and new requirements, and (c) errata".

I didn't review for completeness yet.

CHANGELOG.md Show resolved Hide resolved
CHANGELOG.md Show resolved Hide resolved
CHANGELOG.md Show resolved Hide resolved
CHANGELOG.md Show resolved Hide resolved
Copy link
Member

@rgommers rgommers left a comment

Choose a reason for hiding this comment

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

We had a look at this with a few folks during a call today - all looked clear and complete. So in it goes

@rgommers rgommers merged commit b186a1c into main Dec 15, 2022
@rgommers rgommers deleted the add-changelog branch December 15, 2022 19:31
@rgommers rgommers mentioned this pull request Dec 15, 2022
@asmeurer
Copy link
Member

Is #497 mentioned here? I don't see it.

@asmeurer
Copy link
Member

I would suggest adding this to the site itself somewhere.

@kgryte
Copy link
Contributor Author

kgryte commented Dec 16, 2022

@rgommers
Copy link
Member

I would suggest adding this to the site itself somewhere.

Good suggestion @asmeurer, I've opened gh-577 for this.

rgommers added a commit that referenced this pull request Dec 19, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Narrative Content Narrative documentation content.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants