Polaris Contribution Guidelines

[raquelbreternitz]

We're gathering feedback on the new Contributing section for Polaris.

We've added:

• New guidance on how to know when something should be added to the system
• Tips on how to make different contribution types, from bug fixes to adding UX guidelines
• Guides on crafting your contributions

We want to know if these guidelines are clear and make sense, and identify any gaps we can continue to fill.
We'll use this discussion to collect feedback, so we can make improvements before it launches publicly on Polaris.Shopify.com.

• 👀 Check out our Contribution guidelines to get started.
• 🐛 Found a bug? We separate those from Contributions. If you think something is a bug, please report it here.

💜👩‍🚀✌️ the Polaris team

[dGoligorsky]

Sharing notes as I review all this work, thank you!

• Copy edit: Figuring out what and when to contribute is not always simple, but it doesn't have to be! This reads like it doesn't have to be simple! Maybe could be clearer with something like [...] not always simple, so we're here to help. Or It can be tricky to know when to contribute. Here are some common scenarios [...]
• In the pledge, maybe disability could be ability ? (Regardless of [...] ability [...])?
• Little thing— in numbered lists (like on the contribute > Components page) sometimes there's a . at the end of the list item, sometimes not.
• For icon contributions, curious if you want to add a template for the svg code since it can often have attributes we don't need. Something like <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="<!-- your vector path here -->" fill="#5C5F62"/></svg> ?
• Missing link in markdown on the Designing with a System page: If there's a gap, then [contribute](link to top of contribution page) to the system to make it better.
• Maybe put a link to the When to Contribute New Patterns guide in the Component section about adding a new pattern?
• Missing links in markdown of When to Contribute New Patterns guide: The key here is to [zoom out](link to thinking in systems section). and it's key to [contribute back to the system](insert link to contribution page) if[...]
• I love the mini case studies.
• Also love the guidance for getting set up and opening a PR!

[jjgali]

Thanks @dGoligorsky ! Made a couple issues based on your feedback:

• Icon contribution template for SVG code #6783
• Copy edits to Polaris contribution documentation #6782

[alex-page]

These are wonderful suggestions. Cheers @dGoligorsky.

add a template for the svg code since it can often have attributes we don't need. Something like <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="<!-- your vector path here -->" fill="#5C5F62"/></svg> ?

I am not sure about the icon contribution template for SVG files. The reason is that there could be multiple paths, shapes, groups etc. I do think we can do better in this space but this could be overwhelming or confusing to a designer if they are learning SVG markup.

[peterlazzarino]

Some thoughts as I am going through the process of submitting a component to Polaris. When extending the system, the guide says to Create GitHub issue but in the template, it says that unplanned tickets will be closed and then fall back to a plus one emoji measurement.

For Shopify teams adding proposed changes to Polaris, should we add tickets or just add a PR?

In addition, it would also be helpful, for non-polaris (other team) planned work, how to get that work in the queue for review / acceptance, what type of feedback we can expect, etc.

[raquelbreternitz]

Great questions. @alex-page, do you have a perspective from the dev side on how we should guide these scenarios?

[alex-page]

it says that unplanned tickets will be closed and then fall back to a plus one emoji measurement

I thoroughly dislike this approach. I think we should remove it. Why in my opinion it doesn't work:

1. It closes issues with features and requests making them hard to find
2. It's not encouraging as a person suggesting an excellent feature to have your issue closed
3. It used to be seen as best practice in some open source repositories but now it's quite different. There was a fear that users perceived issues as a sign of an unstable library.

Removing it would allow us to triage, find and collect similar feature requests easily. We could also set up processes to triage issues and correctly label them (only closing if the issue is fixed or not going to be implemented). If people agree I think we should update the issue template. cc @chloerice @yurm04

[peterlazzarino]

I like that a lot, from my end it would be great to be able to open issues in Polaris that pair with features / bugs on our teams boards and track PRs against them.