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

Long term goals #339

Closed
ismay opened this issue Oct 11, 2020 · 18 comments
Closed

Long term goals #339

ismay opened this issue Oct 11, 2020 · 18 comments

Comments

@ismay
Copy link
Member

ismay commented Oct 11, 2020

@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
Copy link
Member

webketje commented Oct 11, 2020

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
Copy link
Member

webketje commented Oct 16, 2020

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>
  1. 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>.

@ismay
Copy link
Member Author

ismay commented Oct 19, 2020

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.

@ismay
Copy link
Member Author

ismay commented Oct 23, 2020

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
Copy link
Member

webketje commented Oct 23, 2020

@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?

@ismay
Copy link
Member Author

ismay commented Oct 24, 2020

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
Copy link
Member

Ajedi32 commented Oct 30, 2020

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
Copy link
Member

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.

@ismay
Copy link
Member Author

ismay commented Oct 30, 2020

@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.

@ismay
Copy link
Member Author

ismay commented Oct 31, 2020

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
Copy link
Member

woodyrew commented Oct 31, 2020 via email

@ibes
Copy link

ibes commented Feb 18, 2021

No updates here?

@ismay
Copy link
Member Author

ismay commented Feb 18, 2021

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
Copy link
Member

How did the meeting go?

@ismay
Copy link
Member Author

ismay commented Apr 17, 2021

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.

@webketje
Copy link
Member

webketje commented Oct 13, 2021

Update on this issue: with legal matters concerning copyright tackled and most practictal transfer hurdles discussed, my aim is to complete the transfer before the end of 2021.

@webketje
Copy link
Member

webketje commented Jan 5, 2022

Over 75% of the work has been done, including:

  • IP & domain name transfer to my business webketje
  • Renaming & GH alignment of core metalsmith plugins under metalsmith org
  • Deprecation of old packages, and republishing of packages under NPM @metalsmith org

Remaining to be deprecated are:

  • metalsmith-layouts
  • metalsmith-markdown
  • metalsmith-in-place (not republished yet)

@webketje
Copy link
Member

Closing since the transfer has been finished in late 2021 and the migration is complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants