search

apostrophecms / apostrophe

A full-featured, open-source content management framework built with Node.js that empowers organizations by combining in-context editing and headless architecture in a full-stack JS environment.
https://apostrophecms.com
Other
4.36k stars 590 forks source link

Problems releasing and publishing packages #3513

Closed zenflow closed 2 years ago

zenflow commented 3 years ago

I've been noticing something weird in this orgs repos. I find a commit like "bumps package version" but the commit is not tagged with the version number, and the new version is not published to npm.

For example:

It made me scratch my head... why would one bump the version number, but not release the new version in any way? It only takes a minute to run npm publish and only a second to run git tag v1.1.0 && git push origin v1.1.0.

But then I figured it out when I saw this commit in the repo for @apostrophecms/seo: https://github.com/apostrophecms/seo/commit/0888e5062ed31ad35e41bfcad828b7b669e9a203#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519 (another commit bumping the package version but having no corresponding git tag or version on npm)

If you're able to npm install apostrophe@^3.7.0 as the commit suggests, then you must be using a private npm registry?

Regardless of publishing to npm, it would be extremely helpful to tag every commit with the semantic version name. This makes things so much more manageable. And it is actually sufficient for installing that version of the package. You can include the dependency as a github tarball url: 

{
  "dependencies": {
    "apostrophe": "https://github.com/apostrophecms/apostrophe/tarball/3.6.0"
  }
}

It might be nice to automate the release process with something like semantic-release to remove all the manual work of making releases (determine next semantic version name, update package.json, update changelog, commit, tag, create GitHub release with release notes, publish to npm), while making sure the latest fixes and features are always available as soon as they're merged.

It's really dead simple to set up. Here's a sample semantic-release configuration & configuration to run it in CI.

The bigger challenge might be getting used to writing the Commit Message Format but it's really great to have commits organized in this way that's easy to read for both humans and robots. Note: If you're ok with the "squash and merge" method of merging PRs on GitHub, then you don't have to write commit messages in this format very often and it's well worth it when you do. Note: You can still "cheat" and make commits that don't have the message format.. they just won't trigger a release or show up in the release notes or changelog.

Thanks for reading and considering :)

boutell commented 3 years ago

Hi Matthew,

With regard to those commits and the discrepancy between that and npm packages appearing, all the releases you mentioned are in npm now. We do PRs internally even for things like version bumps. There's a lag there because of the approval process. However when we're ready we run a script that tags and npm publishes, with no more than a few seconds of discrepancy between.

The semantic release configuration stuff is definitely worth a look. However I think your timing was exceptionally good this morning, as there was no more than about 5 minutes in which you could have seen this discrepancy (:

Also there is also a lag sometimes between "npm publish" succeeding and the npm website actually showing newly published things. That, we can't do anything about.

On Thu, Oct 28, 2021 at 9:07 AM Matthew Francis Brunetti < @.***> wrote:

I've been noticing something weird in this orgs repos. I find a commit like "bumps package version" but the commit is not tagged with the version number, and the new version is not published to npm.

For example:

It made me scratch my head... why would one bump the version number, but not release the new version in any way? It only takes a minute to run npm publish and only a second to run git tag v1.1.0 && git push origin v1.1.0.

But then I figured it out when I saw this commit in the repo for @apostrophecms/seo: @.***

diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519

https://github.com/apostrophecms/seo/commit/0888e5062ed31ad35e41bfcad828b7b669e9a203#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519 (another commit bumping the package version but having no corresponding git tag or version on npm)

If you're able to npm install apostrophe@^3.7.0 as the commit suggests, then you must be using a private npm registry? Are we forgetting to publish to the public npm registry at the same time?

Regardless of publishing to npm, it would be extremely helpful to tag every commit with the semantic version name. This makes things so much more manageable. And it is actually sufficient for installing that version of the package. You can include the dependency as a github tarball url:

{ "dependencies": { "apostrophe": "https://github.com/apostrophecms/apostrophe/tarball/3.6.0" } }

It might be nice to automate the release process with something like semantic-release https://github.com/semantic-release/semantic-release to remove all the manual work of making releases (determine next semantic version name, update package.json, update changelog, commit, tag, create GitHub release with release notes, publish to npm), while making sure the latest fixes and features are always available as soon as they're merged.

It's really dead simple to set up. Here's a sample semantic-release configuration https://github.com/zenflow/generate-ctrl-c-event/blob/master/release.config.js & configuration to run it in CI https://github.com/zenflow/generate-ctrl-c-event/blob/c6ed31155b2e42e34ccf20bcaf116a12968a49e1/.github/workflows/CI.yml#L15-L19 .

The bigger challenge might be getting used to writing the Commit Message Format https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format but it's really great to have commits organized in this way that's easy to read for both humans and robots. Note: If you're ok with the "squash and merge" method of merging PRs on GitHub, then you don't have to write commit messages in this format very often and it's well worth it when you do. Note: You can still "cheat" and make commits that don't have the message format.. they just won't trigger a release or show up in the release notes or changelog.

Thanks for reading and considering :)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/3513, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAH27NHL52PSJVDQQEDHMLUJFDIJANCNFSM5G43DHIQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

--

THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his