Question: Migrating from semantic-release to lerna-semantic-release

jan-molak commented 7 years ago

Hi guys,

First of all, thanks so much for your work on lerna-semantic-release! :-)

Could you please advise on the best way to migrate from semantic-release to lerna-semantic-release for a project which packages have already been published to NPM?

From what I've noticed, semantic-release relies on the NPM to find out the last published version and the commit id associated with it, while lerna-semantic-release relies on git tags

How can I inform/guide/trick lerna-semantic-release to continue where semantic-release had left? Am I right in assuming that if the git tags are created manually, lerna-semantic-release should just pick them up?

Many thanks, Jan

jpnelson commented 7 years ago

Hi! Thanks for your question.

If I understand correctly, you have a package that is currently working with semantic-release, and you'd like to add lerna to that mixture, so you'll have some new packages. So before you had:

a.js
package.json

and now you'll have

packages/
    a
        a.js
        package.json
    b
        b.js
        package.json

To achieve this, you'll want to start releasing with lerna-semantic-release pre/post/perform instead of semantic-release pre/post/perform.

Releases

lerna-semantic-release-get-last-release actually behaves the same as semantic-release's last release behaviour in the normal mode – it uses NPM's gitHead field in the registry to know how far back it should look through the git log for commits associated with a particular package. So, assuming that is up to date, you shouldn't run into problems for the actual release.

(You can see this behaviour here: https://github.com/atlassian/lerna-semantic-release/blob/caribou/packages/lerna-semantic-release-get-last-release/index.js#L7 . The exception is if the package is private – if it is, it will attempt to use git tags to calculate the last version without looking up the NPM registry. You may need to tag your package in the correct way if it is private, but I suspect it isn't for you, if you're using semantic release now).

Changelogs

There will be some differences in how the changelogs are generated though. Semantic release posts directly to github, but lerna-semantic-release can't really do this, as one repository houses multiple packages. So you'll find that it generates changelogs per directory.

Your old commits won't be in the correct format for lerna-semantic-release to pick it up. You could leave the old changelog in a separate file. (There's an issue to make it so that you can enter append mode to preserve the old changelogs: https://github.com/atlassian/lerna-semantic-release/issues/66 )

The changelog generation itself will look for commits in a specific format, rather than the git tag, to know where old versions were released. ( https://github.com/atlassian/lerna-semantic-release/blob/caribou/packages/lerna-semantic-release-post/index.js#L31 is the code associated with that). This was recently changed to not rely on git tags. A "release" commit looks like this:

chore(release): releasing component

affects: a@1.0.0

lerna-semantic-release-post looks for these commits to know how to split up the changelogs – it could be helpful to initially have a commit in your repo like this, or you could just force a release of the old package to kick start the new changelog behaviour.

If this migration is successful for you I'll add it to the README, so please let us know how it goes for you. Thanks!

jan-molak commented 7 years ago

Hi @jpnelson and many thanks for the quick reply!

Yes, your assumptions are correct. The library in question - Serenity/JS uses semantic-release at the moment, but I'm migrating it over to lerna (jan-molak/serenity-js#28). Serenity/JS is an open-source project distributed via public npm packages, so reading the version from npm shouldn't be a problem.

I understand why lerna-semantic-release doesn't post to github - it would become very messy very quickly as github release pages don't really support mono-repos.

I have a couple of questions about the changelogs though.

Existing release notes

Serenity/JS has already had 23 releases. Assemantic-release doesn't use the changelog file but posts the release notes directly to github, they're not stored anywhere in the git history (I think).

As release commits act as markers (?), creating just one release commit now would cause lerna-semantic-release to include the changes from all the previous 23 releases under the current release in the changelog. Is that correct?

My guess is that since the last published release is 1.2.0 and the release commit is marked as a chore, the generate changelog would still state 1.2.0 and list all the changes from all the previous 23 releases. I'll experiment with this in a moment, just wanted to validate if my thinking is correct.

Release commits

As Serenity/JS master doesn't contain any "release commits", lerna-semantic-release will not be able to pick them up, that's why you suggested creating one manually.

I'm a little bit on the fence regarding the release commits, though. They seem to be just lerna-semantic-release-specific meta-data, but as they're created on the master, they'll be picked up by the CI server, unless explicitly ignored. I see you guys are using a [skip ci] marker to skip a CI build for release commits?

Is there any particular reason why those release commits couldn't be created on a separate branch, akin to github pages (so no source code, just the meta-data)? I see several potential benefits to this approach:

it would help with migrating existing projects from semantic-release - I'd just need to create a new branch with a release commit per release.
it would help lerna-semantic-release generate the changelog for existing projects
it would solve the problem of where to store the changelog file, should people want to push it back to git (I'm thinking of including the changelog.md as part of the serenity-js.org website and pushing to github pages, so that doesn't really apply in my case)
it would not pollute the master history with release commits (I imagine that for a project with multiple packages there'd be quite a few release commits)
writing a simple utility that migrates release notes from github to lerna-semantic-release branch would be rather straight-forward, so the migration to mono-repos could be made very simple for people.

... there's of course a downside of having to parse two branches from lerna-semantic-release point of view.

What do you think? J

jan-molak commented 7 years ago

@jpnelson out of curiosity, what was the reason for #21? The Atlassian wiki does not seem to be accessible to the general public.

jpnelson commented 7 years ago

Hi @jan-molak , apologies for the late reply this time – I've added a reference to #21 , see https://github.com/atlassian/lerna-semantic-release/pull/21#issuecomment-288069040 .

I'm also hoping to reply to your other questions some time in the next couple of days :)

jan-molak commented 7 years ago

Hey @jpnelson, thanks for getting back to me.

I've migrated Serenity/JS to Lerna and Lerna Semantic Release (LSR). The only thing that's missing is some elegant handling of the changelogs.

So my outstanding questions could be summed up as:

Could LSR generate a project-level changelog for all the modules alongside the individual changelogs? If generating a project-level changelog allowed for providing a "header" and a "footer" defined in some template files this could solve the problem of migrating existing projects, as the "footer" could contain the release history so far.
Could LSR use a separate branch to store the metadata instead of committing back to master?

Thanks!

jan-molak commented 7 years ago

OK, so it looks like the last missing piece of the puzzle could be solved with gitbook content references and some hacks to move the files where they should be.

Anyway, here's the result of my migration - serenity-js.org/changelog.html

atlassian / lerna-semantic-release