|
| 1 | +# Contributing |
| 2 | + |
| 3 | +[Before contributing](#before-contributing) | |
| 4 | +[Scope](#scope) | |
| 5 | +[Theme code principles](#theme-code-principles) | |
| 6 | +[Contributing code](#contributing-code) | |
| 7 | +[Reporting a bug](#reporting-a-bug) | |
| 8 | +[Reviewing](#reviewing) |
| 9 | + |
| 10 | +We're really glad you're reading this, because we would love to have more developers contribute to this theme! If you're passionate about building for the next million entrepreneurs, you're in the right place. |
| 11 | + |
| 12 | +## Before contributing |
| 13 | + |
| 14 | +If you encounter a bug or think of a useful feature for Dawn, please [create a new issue](https://github.com/Shopify/dawn/issues/new). Creating an issue before jumping into code ensures we can discuss it and determine whether it aligns with the direction of the theme. |
| 15 | + |
| 16 | +If you want to contribute to the theme, regardless of whether it's a small bug fix or correcting a typo, please feel free to do so. Any help goes a long way! Also, contributions aren't necessarily all code related. Other contributions can be in the form of issues, pull requests, discussions, etc. |
| 17 | + |
| 18 | +## Scope |
| 19 | + |
| 20 | +This Github repository exists for the theme development community to discuss and solve problems directly related to Dawn. It **is not the place** to discuss general theme development problems, nor the place to seek help for non-Dawn related problems. |
| 21 | + |
| 22 | +Shopify theme development is a big topic and it's completely normal that you will encounter problems which might require you to reach out for help. In fact, we provide several knowledge and support platforms for theme development already: |
| 23 | + |
| 24 | +* [Shopify Development](https://shopify.dev/themes) |
| 25 | +* [Shopify Help Center](https://help.shopify.com/themes) |
| 26 | +* [Shopify Forum](https://ecommerce.shopify.com/forums) |
| 27 | +* [Shopify Experts](https://experts.shopify.com/) |
| 28 | + |
| 29 | +## Theme code principles |
| 30 | + |
| 31 | +Before contributing to Dawn, please read the following theme code principles to better understand our fundamental approach to theme development. The expectation is that you follow these principles as you build for Dawn. |
| 32 | + |
| 33 | +### Why these principles? |
| 34 | + |
| 35 | +Browsers provide APIs to solve many problems: from [WebGL](https://en.wikipedia.org/wiki/WebGL) and [WASM](https://en.wikipedia.org/wiki/WebAssembly)-powered apps to static websites. The best APIs to use depends on the thing you’re building. Themes power ecommerce websites. In most cases, [Web-native](https://docs.google.com/document/d/11c0EpBmzIPiNrt8hHFz3pnTmEfC7vsC4kktZFoPhhPI/edit#heading=h.fdenrwz0rwne) is a perfect fit for ecommerce websites. Ecommerce needs incredibly fast websites for mostly “logged out” traffic. |
| 36 | + |
| 37 | +### Web-native in its purest form |
| 38 | + |
| 39 | +_The most important principle._ |
| 40 | + |
| 41 | +Themes run on the [evergreen Web](https://www.w3.org/2001/tag/doc/evergreen-web/). We leverage the latest web browsers to their fullest, while maintaining support for the older ones through progressive enhancement—not polyfills. |
| 42 | + |
| 43 | +We write bespoke Web-native code with no abstractions. Frameworks, libraries, and dependencies don’t belong in our themes. |
| 44 | + |
| 45 | +We engage with the browser ecosystem on behalf of our merchants to make Web-native ecommerce the best it can be. |
| 46 | + |
| 47 | +“Don’t repeat yourself” is an anti-pattern. We do our utmost best to do more with less, but we don’t build abstractions around repetition. Instead, we use linting and testing to enforce consistently-good and up-to-date Web-native code. |
| 48 | + |
| 49 | +### Lean, fast, and reliable |
| 50 | + |
| 51 | +_The principle requirement._ |
| 52 | + |
| 53 | +Code must be lean, fast, and reliable. Our targets include: |
| 54 | + |
| 55 | +* Zero [Cumulative Layout Shift](https://web.dev/cls/) |
| 56 | +* No DOM manipulation before user input |
| 57 | +* No render-blocking JavaScript |
| 58 | +* No [long tasks](https://developer.mozilla.org/en-US/docs/Web/API/Long_Tasks_API) |
| 59 | + |
| 60 | +Functionality and design defaults to “no” until it meets this requirement. Code ships on quality. |
| 61 | + |
| 62 | +We relentlessly and continuously optimize code within the constraint of being Web-native. If ever there is a feature that browsers have not made fast yet, we either don’t use it, or use it “as is” if it is fast enough. We trust that browsers will get faster over time. |
| 63 | + |
| 64 | +Themes must be built with purpose. They shouldn’t support each and every feature in Shopify. |
| 65 | + |
| 66 | +### JavaScript not required, fails gracefully |
| 67 | + |
| 68 | +_NoJS is our baseline._ |
| 69 | + |
| 70 | +We extract every bit of speed and functionality out of HTTP, semantic HTML, and CSS before writing our first line of JavaScript. |
| 71 | + |
| 72 | +JavaScript can only be used to progressively enhance features. JavaScript cannot be required to find or purchase products. And the little JavaScript that we use must always fail gracefully, such that every browser gets the most “enhanced” experience that it can within the capabilities that it has. |
| 73 | + |
| 74 | +>:information_source: We do so not because we expect buyers to experience our storefronts with JavaScript disabled, but because it keeps us aligned with the other principles: writing fast, server-rendered, Web-native code. |
| 75 | +
|
| 76 | +### Server-rendered |
| 77 | + |
| 78 | +_Our main constraint._ |
| 79 | + |
| 80 | +HTML must be rendered by Shopify servers using [Liquid](https://shopify.dev/api/liquid). Business logic and platform primitives such as translations and money formatting don’t belong on the client. |
| 81 | + |
| 82 | +Server-rendered doesn’t imply “full page reload”. Async and on-demand rendering of parts of the page is OK, but we do it sparingly as a progressive enhancement. |
| 83 | + |
| 84 | +### Functional, not pixel-perfect |
| 85 | + |
| 86 | +_No buyer is left behind._ |
| 87 | + |
| 88 | +The Web doesn’t require each page to be rendered pixel-perfect by each browser engine. Using semantic markup, progressive enhancement, and clever design, we ensure that themes remain functional regardless of the browser. |
| 89 | + |
| 90 | +And since legacy browsers are often the slowest, we don’t burden them with polyfills. We rely instead on the fail-open nature of the Web to provide them with a “minimal but functional” experience. |
| 91 | + |
| 92 | +## Contributing code |
| 93 | + |
| 94 | +You can follow these steps to go from setting up a store to creating a pull request for Dawn. |
| 95 | + |
| 96 | +>:information_source: We'll assume you're already set up with Git and GitHub (if you're not familiar with these, [start with these docs](https://docs.github.com/en/github/getting-started-with-github/quickstart/set-up-git)). |
| 97 | +
|
| 98 | +1. Set up a [development store](https://shopify.dev/themes/tools/development-stores) so you can test your code changes (assuming you don't already have a store). |
| 99 | +2. Install the [Shopify CLI](https://github.com/Shopify/shopify-cli) by following [these steps](https://shopify.dev/themes/tools/cli/installation). |
| 100 | +3. Fork the repository, clone it and create a new branch: |
| 101 | +```sh |
| 102 | +git clone git@github.com:your-username/dawn.git |
| 103 | +cd dawn |
| 104 | +git checkout -b your-new-branch-name |
| 105 | +``` |
| 106 | +4. Launch a development server: |
| 107 | +```sh |
| 108 | +shopify theme serve |
| 109 | +``` |
| 110 | +5. Add your changes to the codebase. |
| 111 | +6. Commit your changes: |
| 112 | +```sh |
| 113 | +git commit -a -m="Your commit message" |
| 114 | +``` |
| 115 | +7. Push your commit to your forked repository: |
| 116 | +```sh |
| 117 | +git push origin your-new-branch-name |
| 118 | +``` |
| 119 | +8. Open a pull request. See [GitHub's official documentation](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) for more details. |
| 120 | +9. Before you can merge your pull request, you must sign Shopify's [Contributor License Agreement (CLA)](https://cla.shopify.com/). |
| 121 | + |
| 122 | +## Reporting a bug |
| 123 | + |
| 124 | +Bugs are tracked as [GitHub issues](https://github.com/Shopify/dawn/issues). Search open issues to see if someone else has reported a similar bug. If it's something new, [open an issue](https://github.com/Shopify/dawn/issues/new). We'll use the issue to have a conversation about the problem you want to fix. |
| 125 | + |
| 126 | +When creating a new issue, please ensure the issue is clear and include additional details to help maintainers reproduce it: |
| 127 | + |
| 128 | +* **Use a clear and descriptive title** for the issue to identify the problem. |
| 129 | +* **Describe the exact steps which reproduce the problem** in as many details as possible. |
| 130 | +* **Provide specific examples to demonstrate the steps.** Include links to files, or copy/pasteable snippets. If you're providing snippets in the issue, use Markdown code blocks. |
| 131 | +* **Describe the behavior you observed** after following the steps and point out what exactly is the problem with that behavior. |
| 132 | +* **Explain which behavior you expected to see** instead and why. |
| 133 | +* **Include screenshots and animated GIFs** where possible. |
| 134 | + |
| 135 | +## Reviewing |
| 136 | + |
| 137 | +We (the Themes team) review every single PR. The purpose of reviews is to create the best version of Dawn we can for merchants, developers, and others who use it. |
| 138 | + |
| 139 | +:yellow_heart: Reviews are always respectful, acknowledging that everyone did the best possible job with the knowledge they had at the time. |
| 140 | +:yellow_heart: Reviews discuss content, not the person who created it. |
| 141 | +:yellow_heart: Reviews are constructive and start conversation around feedback. |
| 142 | + |
| 143 | +### Self review |
| 144 | + |
| 145 | +You should always review your own PR first. |
| 146 | + |
| 147 | +For code changes, make sure that you: |
| 148 | +- [ ] Confirm that the changes meet our [theme code principles](#theme-code-principles). |
| 149 | +- [ ] Check new or updated Liquid docs to confirm that the code used is up to date and isn't deprecated. |
| 150 | +- [ ] If there are any failing checks in your PR, troubleshoot them until they're all passing. |
| 151 | +- [ ] Add @Shopify/themes-front-end-developers as a reviewer. |
| 152 | + |
| 153 | +### Pull request template |
| 154 | + |
| 155 | +When you open a pull request, you must fill out the "Ready for review" template before we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request. |
| 156 | + |
| 157 | +### Suggested changes |
| 158 | + |
| 159 | +We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch. |
| 160 | + |
| 161 | +As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations). |
0 commit comments