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 'Unreleased' section to changelog; update 'contributing' docs #9532

Closed

Conversation

flarnie
Copy link
Contributor

@flarnie flarnie commented Apr 26, 2017

what is the change?:

  • Add 'Unreleased' section to CHANGELOG
  • Add step to 'contributing' about updating the CHANGELOG

why make this change?:

Whoever does the release of a new React version must manually read
through the recent git history and write the CHANGELOG update.

If we incrementally add to the CHANGELOG under the 'Unreleased' header,
as we make PRs, then to release a new version will just be updating
'Unreleased' to be the new version number and adding a blank section for
'Unreleased'.

See http://keepachangelog.com/en/0.3.0/ for more info about this idea.

test plan:
Visual verification of the change, and also I built the website locally
and inspected the change.
screen shot 2017-04-26 at 7 57 07 am

issue:
#9527

**what is the change?:**
- Add 'Unreleased' section to `CHANGELOG`
- Add step to 'contributing' about updating the `CHANGELOG`

**why make this change?:**

Whoever does the release of a new React version must manually read
through the recent git history and write the CHANGELOG update.

If we incrementally add to the CHANGELOG under the 'Unreleased' header,
as we make PRs, then to release a new version will just be updating
'Unreleased' to be the new version number and adding a blank section for
'Unreleased'.

See http://keepachangelog.com/en/0.3.0/ for more info about this idea.

**test plan:**
Visual verification of the change, and also I built the website locally
and inspected the change.

**issue:**
facebook#9527
@flarnie
Copy link
Contributor Author

flarnie commented Apr 26, 2017

I think the next step is to start back-filling the 'Unreleased' section, as well as adding the notes from the 15.5.* updates and for the upcoming 15.6 update. I'll work on that in a separate PR.

@flarnie
Copy link
Contributor Author

flarnie commented Apr 26, 2017

Thanks @gaearon - since you are so active in reviewing PRs I am reassured that you have no issues with this change.

@gaearon
Copy link
Collaborator

gaearon commented Apr 26, 2017

We'll need to work out how this works with:

  • Major / minor releases (e.g. do we put breaking changes there)
  • Visibility: this section can get large and confuse people who expect the info about latest release there. Maybe worth collapsing it somehow (does <details> tag work in Markdown?)

**what is the change?:**
Fix the numbers in a list

**why make this change?:**
They were incorrect due to an oversight in the previous commit.

**test plan:**
Look at the docs.

**issue:**
facebook#9527
@flarnie
Copy link
Contributor Author

flarnie commented Apr 26, 2017

Major / minor releases (e.g. do we put breaking changes there)

I'm not sure this affects our decisions about where to put breaking changes. You are right that our current situation makes things complicated - we have v15.6 and the continuing snowball of 16.0, both in development at the same time. Here is my thought for that:

## [Unreleased]
// ... Anything that is on master but not cherry-picked to 15.*

## 15.6 [Unreleased]
// ... I will backfull the changelog and continue updating it as we merge things into 15.6, then remove the '[Unreleased]' part when releasing this.

## 15.4
// ... the changelog for 15.4

// ... rest of the CHANGELOG

When something is merged to master, we add a line under 'Unreleased'. And that's how it will work post 16.0, when there is just one branch and we release from master.

For now, when something gets cherry-picked from master I would move the line from 'Unreleased' to '15.6 [Unreleased]'.

**what is the change?:**
see title

**why make this change?:**
This will make the change log easier to read for folks who are just
looking for info about the latest stable release.

**test plan:**
Visual inspection.

**issue:**
@flarnie
Copy link
Contributor Author

flarnie commented Apr 27, 2017

Current plan for this:

  1. Land Update Changelog for v15.5.1-15.5.4 #9537
  2. Backfill a section for '15.6.0 [Unreleased]' and also collapse that in a 'details' tag. Edit: - this pr - Add 'unreleased' incremental change log for v15.6.0 #9544
  3. Update this PR to backfill at least the basics of what is currently on master and not on the 15.6-dev branch.
  4. Land this.

7. Format your code with [prettier](https://github.com/prettier/prettier) (`npm run prettier`).
8. Run the [Flow](https://flowtype.org/) typechecks (`npm run flow`).
9. If you added or removed any tests, run `./scripts/fiber/record-tests` before submitting the pull request, and commit the resulting changes.
10. If you haven't already, complete the CLA.
Copy link
Collaborator

Choose a reason for hiding this comment

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

When we change this we usually also want to change the GitHub pull request template (unless you already have). It's in .github folder.

@flarnie
Copy link
Contributor Author

flarnie commented Aug 12, 2017

Thinking of revisiting this now that we are getting close to the 16.0 RC. Will come back to it after wrapping up any bug fixes I can help with.

@flarnie
Copy link
Contributor Author

flarnie commented Sep 18, 2017

Closing this in favor of #10730

@flarnie flarnie closed this Sep 18, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants