Docs: Extend guidelines for managing packages and publishing them to npm #8768

gziolo · 2018-08-09T11:19:49Z

Description

As discussed during the JavaScript weekly chat earlier this week, I opened pull request to extend our guidelines for managing and publishing npm packages with Lerna.

TODO

creating new packages
Babel dependencies
maintaining changelogs

gziolo · 2018-08-09T12:58:46Z

Problem: Publishing modules to npm can be difficult because it is not always clear at the time of publishing to what version the package should be updated. The individual performing the publish is not always the same as the contributors who had proposed changes to the package.

Options:

Adopt conventional commits to enable automatic versioning (pull request)
- Issue: This is hard to enforce
Encourage developers to introduce relevant changelog entries as part of proposed changes. The type of change should indicate versioning requirements.
- Issue: Not every version bump is caused by directly by new changes, sometimes indirectly by updated dependencies.
- Issue: Prone to frequent merge conflicts with many developers adding entries to the same text file.

Decision: Encourage developers to introduce changelog entries and evaluate success in a future meeting.

gziolo · 2018-08-13T11:18:08Z

@hypest feel free to include react-native in the package.json example. We probably should add a note that it should be added only for packages which are meant to be sent to the user. It doesn't make sense in the context of build tools.

aduth · 2018-08-14T18:19:51Z

It occurred to me: Maybe it shouldn't be the releaser who touches the version, but instead the developer who proposes a change. If, for example, a current changelog appears as:

## v1.2.2 (Unreleased)

- Fix: ...
- Fix: ...

If I need to add something considered a bugfix, I add the "Fix:" item and ~~change version to 1.2.3~~ leave the version as 1.2.2 (see correction notes)
If it's a new feature I'm adding, I add the "New:" item and change version to 1.3.0
If it's a breaking change I'm introducing, I add the "Breaking:" item and change version to 2.0.0
- And at this point it becomes extremely obvious to me whether I should consider pushing 1.2.2 before introducing the breaking change so as to ensure the fixes are shipped separate to a major version bump.

Thoughts? In retrospect, this is my workflow for how I manage my own personal projects.

gziolo · 2018-08-14T21:25:59Z

That’s a really good idea. We can almost copy and paste what you described. I would also encourage grouping by:

Breaking
New
Fix

And skip everything else from the changelog. This is what popular repositories do usually.

aduth · 2018-08-15T14:59:20Z

A correction to my previous comment, which is worth clarifying as it's a potential point of confusion:

If I need to add something considered a bugfix, I add the "Fix:" item and change version to 1.2.3

In my above example, since the existing "1.2.2" version is marked unreleased, I shouldn't change the version at all.

Similarly, if the version was "1.3.0 (Unreleased)" and I was adding a new feature, I wouldn't change the version.

The version bump is only necessary if (a) there are no other unreleased changes or (b) the type of change I'm introducing is incompatible (more severe) than the other unreleased changes.

gziolo · 2018-08-21T09:48:48Z

This is ready for a final check. I included all suggestions shared by @aduth. Thanks for help 💯

ntwb

LGTM

gziolo · 2018-08-21T11:23:01Z

@ntwb, thanks for your verbiage tweaks 🙇

aduth · 2018-08-21T12:32:25Z

CONTRIBUTING.md

+		}
+	}
+	```
+	It assumes that code is goind to be located in `src` folder and will be transpiled with `Babel`.


Typo: "goind" -> "going"

aduth · 2018-08-21T12:32:40Z

CONTRIBUTING.md

+	```
+3. `README.md` file containing at least:
+	- Package name.
+	- Package description.


Same as in package.json ? (Should we mention this?)

It isn't always the case. Not sure to be honest.

aduth · 2018-08-21T12:33:01Z

CONTRIBUTING.md

+	- Package description.
+	- Installation details.
+	- Usage example.
+	- `Code is Poetry` logo.


Where does one find this?

We should include the snippet. It's copy and paste anyways.

aduth · 2018-08-21T12:33:19Z

CONTRIBUTING.md

+
+### Maintaining changelogs
+
+It isn't easy task to maintain dozens of npm packages. That's why we decided to introduce `CHANGELOG.md` files for all packages to simplify the release process.


Grammar: "It isn't an easy"

aduth · 2018-08-21T12:34:16Z

CONTRIBUTING.md

+```md
+## v1.2.2 (Unreleased)
+
+#### Bug Fix


Based on document structure, why would this be an H4 following an H2 ?

I blame Babel, will update :)

aduth · 2018-08-21T12:36:28Z

CONTRIBUTING.md

+
+- If you need to add something considered a bug fix, you add the item to `Bug Fix`section and leave the version as 1.2.2.
+- If it's a new feature you add the item to `New Feature` section and change version to 1.3.0.
+- If it's a breaking change you want to introduce, you add the item to `Breaking Change` section and bump the version to 2.0.0.


Are there any other changes which wouldn't fall neatly under one of these classifications? I've personally observed some "Internal" / "Housekeeping" type changes which don't necessarily contribute to public-facing consumer, though I suppose could have some place in the SemVer hierarchy. These are also items it's not entirely clear we'd need to include at all.

These are also items it's not entirely clear we'd need to include at all.

It might get tricky because Lerna will bump version anyways. We probably should skip them as they aren't that important but we still will have a new version released. It might sometimes happen only because one of the packages maintained by Lerna listed in dependencies has version bump.

tofumatt

Sorry this took me ages to get to, I got distracted with some other PRs! 😓

I made a few tweaks and tidied up some of the docs based on @aduth's comments. The rest looks good to me. 👍

aduth · 2018-08-21T20:47:22Z

CONTRIBUTING.md

+
+### Maintaining changelogs
+
+Maintaining dozens of npm packages is difficult–it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. All packages should follow the [Semantic Versioning (`semver`) specification](https://semver.org/).


The ultimate nitpick! If we're going to be fancy with dashes, we should use the correct one: here an en dash should be the em dash 😄

Before: –
After: —

Omg you’re totally right and I’m often the one to comment on that. I have no excuse!

tofumatt · 2018-08-21T22:53:54Z

Sorry about my rubbish commit message, I made it from my iPad and fat-fingered the return key.

@aduth

Added @aduth suggestion from the core JS chat: https://make.wordpress.org/core/2018/08/21/javascript-chat-summary-august-21/.

gziolo · 2018-08-22T07:51:31Z

Thanks @tofumatt and @aduth for your help 🙇 Let's see how those guidelines influence daily workflow and iterate later.

gziolo added [Type] Developer Documentation Documentation for developers npm Packages Related to npm packages labels Aug 9, 2018

gziolo self-assigned this Aug 9, 2018

gziolo requested review from youknowriad, pento, ntwb, aduth and adamsilverstein August 9, 2018 11:19

gziolo added the [Status] In Progress Tracking issues with work in progress label Aug 9, 2018

gziolo requested a review from hypest August 13, 2018 11:17

aduth mentioned this pull request Aug 14, 2018

Framework: Remove deprecations slated for 3.6 removal #8993

Merged

gziolo and others added 4 commits August 21, 2018 11:43

Docs: Extend guidelines for publishing packages to npm

8a64cce

Docs: Add details about creating new package

c4bc273

Add React Native entrypoint in example package.json

035fd9f

Docs: Add managing packages section

3f52844

gziolo force-pushed the update/publishing-docs branch from a9889dd to 3f52844 Compare August 21, 2018 09:43

Docs: Tiny fix in CONTRIBUTING.md file

ec0d7f6

gziolo removed the [Status] In Progress Tracking issues with work in progress label Aug 21, 2018

Docs: Tiny title fix in CONTRIBUTING.md file

d09e885

gziolo added this to the 3.7 milestone Aug 21, 2018

ntwb added 2 commits August 21, 2018 20:04

Minor verbiage tweak to _Major version_ semver

3a034a1

Revert accidental changes added in 3a034a1

24e63dd

ntwb approved these changes Aug 21, 2018

View reviewed changes

tofumatt self-assigned this Aug 21, 2018

gziolo requested review from ntwb and tofumatt August 21, 2018 11:28

aduth reviewed Aug 21, 2018

View reviewed changes

tofumatt added 2 commits August 21, 2018 20:14

docs: Make npm consistent and tweak a few things

3883da5

docs: Tweaks for readability, typo fixes, etc.

48496f7

tofumatt approved these changes Aug 21, 2018

View reviewed changes

aduth reviewed Aug 21, 2018

View reviewed changes

Use

e38ebff

Update CONTRIBUTING.md

ccf0813

Added @aduth suggestion from the core JS chat: https://make.wordpress.org/core/2018/08/21/javascript-chat-summary-august-21/.

gziolo merged commit abac58c into master Aug 22, 2018

gziolo deleted the update/publishing-docs branch August 22, 2018 07:51

aduth mentioned this pull request Aug 23, 2018

Add CHANGELOG.md files for each package #7800

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Extend guidelines for managing packages and publishing them to npm #8768

Docs: Extend guidelines for managing packages and publishing them to npm #8768

gziolo commented Aug 9, 2018 •

edited

Loading

gziolo commented Aug 9, 2018

gziolo commented Aug 13, 2018

aduth commented Aug 14, 2018 •

edited

Loading

gziolo commented Aug 14, 2018 •

edited

Loading

aduth commented Aug 15, 2018

gziolo commented Aug 21, 2018

ntwb left a comment

gziolo commented Aug 21, 2018

aduth Aug 21, 2018

aduth Aug 21, 2018

gziolo Aug 21, 2018

aduth Aug 21, 2018

gziolo Aug 21, 2018

aduth Aug 21, 2018

aduth Aug 21, 2018

gziolo Aug 21, 2018

aduth Aug 21, 2018

gziolo Aug 21, 2018

tofumatt left a comment

aduth Aug 21, 2018

tofumatt Aug 21, 2018

tofumatt commented Aug 21, 2018

gziolo commented Aug 22, 2018


		### Maintaining changelogs

		It isn't easy task to maintain dozens of npm packages. That's why we decided to introduce `CHANGELOG.md` files for all packages to simplify the release process.


		### Maintaining changelogs

		Maintaining dozens of npm packages is difficult–it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. All packages should follow the [Semantic Versioning (`semver`) specification](https://semver.org/).

Docs: Extend guidelines for managing packages and publishing them to npm #8768

Docs: Extend guidelines for managing packages and publishing them to npm #8768

Conversation

gziolo commented Aug 9, 2018 • edited Loading

Description

TODO

gziolo commented Aug 9, 2018

gziolo commented Aug 13, 2018

aduth commented Aug 14, 2018 • edited Loading

gziolo commented Aug 14, 2018 • edited Loading

aduth commented Aug 15, 2018

gziolo commented Aug 21, 2018

ntwb left a comment

Choose a reason for hiding this comment

gziolo commented Aug 21, 2018

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tofumatt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tofumatt commented Aug 21, 2018

gziolo commented Aug 22, 2018

gziolo commented Aug 9, 2018 •

edited

Loading

aduth commented Aug 14, 2018 •

edited

Loading

gziolo commented Aug 14, 2018 •

edited

Loading