Migration docs v3 to v4

[AndrewMusgrave]

WHY are these changes introduced?

Documentation

WHAT is this pull request doing?

Documenting. This is adding a text file to the repo, it doesn't get published anywhere fancy.

[kaelig]

I'd recommend prefixing all of these anchors because for example #navigation already exists in the style guide.

[AndrewMusgrave]

Afaik we can't prefix them since they're based on the headers. I'm not 100% positive though, would love to hear how, if there is one 😄

[kaelig]

Yeah there is! Named anchors should do the trick

[kaelig]

cc @amrocha (in case you haven't been pinged yet)

[amrocha]

@AndrewMusgrave I'm not sure I understand what the issue here is, can you give an example?

[AndrewMusgrave]

I may be using the API wrong but string's dont seem to work for iconBody or icon#source

function Playground() {
  const icon =
    "<svg><path d='M17 9h-6V3a1 1 0 1 0-2 0v6H3a1 1 0 1 0 0 2h6v6a1 1 0 1 0 2 0v-6h6a1 1 0 1 0 0-2'  fill-rule='evenodd'/></svg>";
  return (
    <Fragment>
      <Icon source={icon} />
      <Navigation location="/">
        <Navigation.Section
          items={[
            {
              url: '/path/to/place',
              label: 'Products',
              icon,
            },
          ]}
        />
      </Navigation>
    </Fragment>
  );
}

@amrocha

[amrocha]

I think that's just something wrong with the SVG you're using, when I updated it to the following SVG it started working again:

<svg viewBox='0 0 20 20' xmlns='http://www.w3.org/2000/svg'><path d='M10.707 17.707l5-5a.999.999 0 1 0-1.414-1.414L11 14.586V3a1 1 0 1 0-2 0v11.586l-3.293-3.293a.999.999 0 1 0-1.414 1.414l5 5a.999.999 0 0 0 1.414 0' /></svg>

[AndrewMusgrave]

TIL: xmlns is required for image/svg+xml files which is how we server string icons

[amrocha]

ah yeah, it needs be XML compliant

[selenehinkley]

Can we include any info that would let the person know when the guide applies to v2? Just wondering how they would know if it applies

[AndrewMusgrave]

We didn't have a lot of breaking changes in v3 so a lot of this guide will apply. If you think this could be jarring, we could omit it?

[selenehinkley]

I think the title saying Migrating from v3 to v4 clarifies what it's for. I'm mainly wondering if folks would want a link to more info about v2 so they can find out why we say "this guide may apply to v2" - I'd like them to have a link or more info so they can figure that out. Unless that's something they should already know?

[selenehinkley]

It would be good to introduce this list with a label that lets the reader know what the list is for or what it is made up of. Something like, Navigation components:

[selenehinkley]

Suggested change

	In v3, you could hook into Polaris’ context types.
	In v3, you could hook into Polaris React’s context types.

[selenehinkley]

Some suggestions to the wording to add clarity.

[BPScott]

A note to myself: remember to talk about moving from sdks.shopfiycdn.com to unpkg.com for CDN CSS assets

[dleroux]

@BPScott left some suggestions. Do you mind going over them and committing where you see fit?

[selenehinkley]

test - ignore this... I didn't see my review posts earlier in the feed so I clicked submit review again to see if they'd pop up. found them :)