Public readiness checklist

[ctreatma]

As of now, this repo is set to private/internal while we fill in some gaps to make it ready for other teams & for external customers. Once this is ready for public consumption, we will delete the repo and recreate it to ensure that any unnecessary releases/tags/etc. are cleaned up.

Before this goes public, we need to:

• [x] Fill in the README with customer-facing information
• [x] Add a CONTRIBUTING document that includes contribution guidelines
• [x] Add a DEVELOPMENT document that includes: how to get set up for local development, how to onboard a new service, how to update an existing service, how to cut a release
• [x] Update examples to use this SDK instead of metal-go to demonstrate that this is a drop-in replacement
• [x] Enable branch protection on main

Steps for going public:

• [x] Cut a release that only includes the module name / package structure change (is otherwise identical to the last metal-go release
• [x] Transfer remaining issues from equinix-labs/metal-go to this repo
• [x] Deprecate equinix-labs/metal-go and include a link to this repo
• [x] Update or replace metal-go Labs page with a page for this SDK

[displague]

https://go.dev/doc/go1.4#canonicalimports provides a way to make old metal-go references use the new location.

A symlink in the root metal -> services/metal would also help prevent old dependencies from breaking. This could be done with fabric-go too, perhaps. I wonder if there is a better approach than a symlink, something more Go idiomatic, perhaps within go.mod.

We should be able to take both of these approaches.

I like the idea of migrating metal-go over to Equinix as a replacement for this project (with that, merging in the changes from this repo). If we followed that pattern, fabric-go could be grafted/merged in a way that preserves intent, times, and contributor attribution. If we were to do that, we would want to reconcile tags in some wa, I think. Fabric is at 0.7.1, Metal 0.27.0.

[ctreatma]

Based on this, I don't think we can use canonical imports here:

With this in place, the go command will refuse to compile a package that imports github.com/rsc/pdf, ensuring that the code can be moved without breaking users.

My reading of that is that if we add a canonical import to the metal package in this project, users will be able to import it using the old metal-go import path, but will not be able to import it using the new, preferred path. I haven't found anything indicating that we can provide multiple canonical imports; is that a thing we can do?

[displague]

I mean we would add the canonical path (equinix-sdk-go/foo) to equinix-labs/metal-go/metal/v1. Something I didn't notice about this feature is that Go will refuse to compile the dependent package until the metal-go path has been updated to the new canonical package URL. That may not be so bad if the warnings make it clear.

[ctreatma]

I'm leaning towards keeping metal-go where it is and introducing this SDK as a separate repo. It doesn't seem like canonical paths eliminate any steps for migration; as I understand it, users will still have to update their import statements whether we add a canonical path to metal-go or not. I think the biggest pain point with keeping this repo separate is that I'll need to copy the remaining open issues over here, but that's a one-time thing.

[ctreatma]

This repo is now public; due to the way GitHub permissions are set up for this org, I couldn't delete this repo anyway, so I just flipped it public as-is.

v0.30.0 has been released, with equivalent functionality to equinix-labs/metal-go@v0.29.0.