Long term goals

@webketje @woodyrew @Ajedi32

I thought I'd create a dedicated issue to discuss the long term plans I alluded to in my comment in #338 (comment). We (@webketje @woodyrew) already discussed this a bit, but I thought it'd be good to write something down so @Ajedi32 knows what we've discussed as well, and so we can get some clarity on the exact steps to take.

I assume we all agree that the current fragmentation of metalsmith codebases over different organisations is confusing our users. Plus I think permissions have been a bit of an issue. We can discuss steps to address this, I'll update the below section in this comment with the latest form of the plan (feel free to edit if incorrect or out of date):

Migrate repos

For the new repositories (in the metalsmith org):

• We're mirroring the repos, not forking.
• The new names omit the metalsmith- prefix (update package name as well)
• Make sure to include the git tags as well.
• Update all references in the codebase to the new repo location
• Add gh repo topic tags

For the old repositories (in the segmentio org):

• Add a clear deprecation message in the README (with a link to the new location). for example: This library is no longer maintained. Please migrate to the replacement at github.com/metalsmith/{replacement} & npmjs.com/{replacement}
• In the interest of clarity I think we should close all PRs and issues on the segment.io repos, with a clear message stating that the repos have been moved to the metalsmith org. We should also add issue and PR templates stating the same, and if possible close issues entirely. Probably best to hold off on this until we have a clear message that we all agree on.
• Archive the repository

For repositories already under metalsmith org:

• I'd say we just rename the repo to omit the metalsmith- prefix, and follow the other appropriate steps from the For the new repositories section above

Migrate npm packages

• Republish latest version on npm under @metalsmith npm org (with a patch bump, so that the git tags won't be out of sync with the npm versions)
• Deprecate the original packages

[webketje]

Full procedure for migrating a repo (point 1):

1. Create repo on GH under metalsmith & rename (including Readme.md mentions) omitting 'metalsmith-': https://github.com/metalsmith/permalinks
2. Add Github topic tags (metalsmith, metalsmith-plugin, ...other keywords).
3. Local clone of segmentio/metalsmith-, change git origin to new repo & push
4. Republish latest version on NPM under @metalsmith org: https://www.npmjs.com/package/@metalsmith/permalinks
5. Push a deprecation message (& redirect) to the README's of the repo's at segmentio
6. Deprecate the original package with npm deprecate https://docs.npmjs.com/cli/deprecate

[webketje]

Migration plan: Full proposal

This comment will be updated with subsequent feedback & agreements. Please provide feedback within a reasonable timeframe.

What needs to be migrated?

1. Github metalsmith core repository
2. Github plugin repositories
3. NPM packages for both
4. Website docs

Roadmap

Begin 2021: migrate Github repositories, NPM packages
Mid 2021: update website contents, Github metadata (=resolve remaining issues & PR's, release patch/minor versions)
After: new developments & updates

Migrate Github repository

Steps for the new repository (metalsmith/<repo>)

1. Create repo on GH in metalsmith org, named <plugin> (without metalsmith- prefix).
2. Clone the segmentio/metalsmith-* repository locally, make sure to git fetch --tags.
3. Add a commit in which all package.json/ Readme.md mentions of metalsmith-<plugin> are renamed to @metalsmith/<plugin>.
4. git remote set-url origin <new-repo-git-url>, git push origin master, then git push --tags.
5. Add Github topic tags in the repo settings (metalsmith, metalsmith-plugin, ...other keywords).

Steps for the old repository (segmentio/metalsmith-<repo>)

1. Push a deprecation message (& redirect) to the README's of the repo's at segmentio. Anyone can make a PR with these changes, repo owners should review/ accept.
   Generic proposal (in markdown) for a Readme.md notice [keep in mind that on NPM both the Readme notice & the npm deprecate message will be visible, so we might want to make the Readme notice both significant on its own and complementary with the NPM notice]:

# DEPRECATED/ MOVED
Active development for this repository has moved to <https://github.com/metalsmith/repo>

2. Archive the repository (eventually, requires coop from segmentio)

Steps for repositories already under metalsmith org (metalsmith/metalsmith-<repo>)

Either we treat the existing repository as new (without the tags/ remotes part) - OR we create a new repo and follow the procedure in the 2 previous sections (cf. above). Personally in favor of option 1, as this avoids having to migrate issues & PR's.

Migrate Github metadata (issues/PR's)

Pressing issues observed by users can be ported by them to the new repository's. The majority of issues and PR's without interaction after 2017 can probably be safely closed. Relevant issues and PR's can remain in the segmentio issue trackers, and we can use them as a backlog for a pro-active approach: the metalsmith team can scan through them and eventually port relevant issues directly in commits in new PR's.

Migrate NPM packages

1. Republish latest version on NPM under @metalsmith org: npm publish --access=public
2. Deprecate the original package with npm deprecate <pkg> <msg> (cf. https://docs.npmjs.com/cli/deprecate).
   This has already been done for metalsmith-permalinks with <msg> being: No longer maintained; Migrate to the following package: @metalsmith/permalinks

"Migrate" the website contents

The website contents can only be migrated once all main packages are migrated on NPM. With migrating in this context needs to be understood: changing all references to metalsmith-<plugin> to @metalsmith/<plugin>.

Thanks @webketje. The broad lines of this all look good to me. There are a couple of details that are unclear to me or warrant some further discussion (in my opinion). Nothing major though. I'll write a more detailed reply coming friday, when I have more time to take a proper look.

Ok, I've gone through your suggestions and made a couple of edits. So this is what I'd propose as a combination of what we've both suggested:

Migrate repos

For the new repositories (in the metalsmith org):

• We're mirroring the repos, not forking.
• The new names omit the metalsmith- prefix (update package name as well)
• Make sure to include the git tags as well.
• Update all references in the codebase to the new repo location
• Add gh repo topic tags

For the old repositories (in the segmentio org):

• Add a clear deprecation message in the README (with a link to the new location)
• In the interest of clarity I think we should close all PRs and issues on the segment.io repos, with a clear message stating that the repos have been moved to the metalsmith org. We should also add issue and PR templates stating the same, and if possible close issues entirely. Probably best to hold off on this until we have a clear message that we all agree on.
• Archive the repository

For repositories already under metalsmith org:

• I'd say we just rename the repo to omit the metalsmith- prefix, and follow the other appropriate steps from the For the new repositories section above

Migrate npm packages

• Republish latest version on npm under @metalsmith npm org
• Deprecate the original packages

Notes

I've removed the planning deadlines and plans dealing with the website. I think that the deadline won't have a lot of influence on our actual productivity, seeing as we're a small team of people with limited time. We'll just try and get it done as fast as is reasonably possible. And about the website, I think we can tackle the plans for that after we've dealt with this (just to keep the scope of this issue contained).

Feedback is welcome. Let's leave this up for a while so people have time to give their feedback. And if noone objects to this I'd say we can assume it's fine and proceed.

[webketje]

@ismay can you also provide feedback / suggestion for:

Generic proposal (in markdown) for a Readme.md notice [keep in mind that on NPM both the Readme notice & the npm deprecate message will be visible, so we might want to make the Readme notice both significant on its own and complementary with the NPM notice ("No longer maintained; Migrate to the following package: @metalsmith/permalinks")]

Also, I just thought about this: if we republish the same version on NPM after we first add a commit changing name references, then the Git tags will be out of sync with the NPM versions.. So we might wanna change that to "publish a patch version", what do you say?

@woodyrew can you also have a look?

Also, I just thought about this: if we republish the same version on NPM after we first add a commit changing name references, then the Git tags will be out of sync with the NPM versions.. So we might wanna change that to "publish a patch version", what do you say?

Ah yeah. Yeah a patch version sounds good. In the changelog I'd just mention the name change / migration, so that people know why there was a patch bump.

Generic proposal (in markdown) for a Readme.md notice [keep in mind that on NPM both the Readme notice & the npm deprecate message will be visible, so we might want to make the Readme notice both significant on its own and complementary with the NPM notice ("No longer maintained; Migrate to the following package: @metalsmith/permalinks")]

I'd say something like: "This library is no longer maintained. Please migrate to the replacement at github.com/metalsmith/{replacement} & npmjs.com/{replacement}".

[Ajedi32]

Finally got around to looking at this; seems reasonable to me. Do you want to try to do the migration all at once, or just start migrating repos one at a time? Doing it all at once seems like it'd make for a better user experience, but would likely require a certain degree of focused effort to complete the transition in a reasonable amount of time.

[woodyrew]

Hi all,

The process looks reasonable to me, I think the only consideration is to make sure our messaging is positive about the continuation and future of the project under the Metalsmith organisation.

The "mirroring" and transferring of the repositories shouldn't be a big issue in terms of time but I greatly appreciate the realism of the time frames suggested. It would be good to get a list of repos we wish to bring under the metalsmith org umbrella.

Could we update the opening comment in this thread to include the latest form of the plan and update that as necessary, I think we should all have edit rights to do so. Please post a comment to accompany the change for traceability. I there is another way to do this that's more appropriate please do that instead.

Also, I just thought about this: if we republish the same version on NPM after we first add a commit changing name references, then the Git tags will be out of sync with the NPM versions.. So we might wanna change that to "publish a patch version", what do you say?

I think a patch version would be the best idea.

@Ajedi32 Didn't notice that I was replying to a github thread, I thought it was the email thread I was replying to, sorry about that 😅 Removed my comment as it wasn't really about what was being discussed in this thread.

Could we update the opening comment in this thread to include the latest form of the plan and update that as necessary, I think we should all have edit rights to do so. Please post a comment to accompany the change for traceability. I there is another way to do this that's more appropriate please do that instead.

I've updated the top comment with the latest version of the plan. Let me know if I've made any mistakes or forgotten anything.

The process looks reasonable to me, I think the only consideration is to make sure our messaging is positive about the continuation and future of the project under the Metalsmith organisation.

I agree, that sounds good.

The "mirroring" and transferring of the repositories shouldn't be a big issue in terms of time but I greatly appreciate the realism of the time frames suggested. It would be good to get a list of repos we wish to bring under the metalsmith org umbrella.

Do you want to try to do the migration all at once, or just start migrating repos one at a time? Doing it all at once seems like it'd make for a better user experience, but would likely require a certain degree of focused effort to complete the transition in a reasonable amount of time.

One important thing I think, before we continue with the plan, is that currently Segment is looking into whether a transfer of the github repos to the metalsmith org would be possible for them. They'll get back to us on that next week. I think it'd be good to wait for that, since that seems like the ideal solution to me. What do you guys think?

[woodyrew]

One important thing I think, before we continue with the plan, is that currently Segment is looking into whether a transfer of the github repos to the metalsmith org would be possible for them. They'll get back to us on that next week. I think it'd be good to wait for that, since that seems like the ideal solution to me. What do you guys think?

Yes, I'm happy to see what they come back with.

…

On Sat, 31 Oct 2020, 09:37 ismay, ***@***.***> wrote: Could we update the opening comment in this thread to include the latest form of the plan and update that as necessary, I think we should all have edit rights to do so. Please post a comment to accompany the change for traceability. I there is another way to do this that's more appropriate please do that instead. I've updated the top comment with the latest version of the plan. Let me know if I've made any mistakes or forgotten anything. The process looks reasonable to me, I think the only consideration is to make sure our messaging is positive about the continuation and future of the project under the Metalsmith organisation. I agree, that sounds good. The "mirroring" and transferring of the repositories shouldn't be a big issue in terms of time but I greatly appreciate the realism of the time frames suggested. It would be good to get a list of repos we wish to bring under the metalsmith org umbrella. Do you want to try to do the migration all at once, or just start migrating repos one at a time? Doing it all at once seems like it'd make for a better user experience, but would likely require a certain degree of focused effort to complete the transition in a reasonable amount of time. One important thing I think, before we continue with the plan, is that currently Segment is looking into whether a transfer of the github repos to the metalsmith org would be possible for them. They'll get back to us on that next week. I think it'd be good to wait for that, since that seems like the ideal solution to me. What do you guys think? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#339 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOQL4C4XV4JDUNHCPAYFLTSNPLE5ANCNFSM4SLV4H2Q> .

[ibes]

No updates here?

No updates here?

It's in progress. We have a meeting with representatives from Segment on the 26th. We'll keep the community posted!

[leviwheatcroft]

How did the meeting go?

Pretty good. It seems like the most likely route will be one of the current maintainers taking over the metalsmith IP. Currently we're awaiting the draft of some legal documents to arrange that, and then after that it should hopefully be possible for us to move along with the reorganisation.