diff --git a/DEVELOP.md b/DEVELOP.md index 8130b4f6..4280c7cb 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -1,48 +1,68 @@ # Primer Development -If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way. +If you've made it this far, **thank you**! We appreciate your contribution, and hope that this document helps you along the way. If you have any questions or problems, don't hesitate to [reach out to us on Spectrum](https://spectrum.chat/primer). ## Structure -The project is structured as a [monorepo] made up of lots of small npm modules, many of which depend on each other. We use [Lerna] to manage, version, and publish all of the packages together. +Primer CSS is published to [npm] as [@primer/css]. Each of Primer CSS's "modules" lives in git as a directory of SCSS source files under `src/` with an `index.scss` in it. Generally speaking, the styles are divided into three primary themes: + +* **Core** styles (in `core/`) are common dependencies, which include support variables, native element and typography styles, buttons, navigation, tooltips, etc. +* **Product** styles (in `product/`) are specific to github.com, and include components such as avatars, labels, markdown styles, popovers, and progress indicators. +* **Marketing** styles (in `marketing/`) are specific to GitHub marketing efforts, including international and event-focused sites as well as the more design-heavy feature pages on github.com. Marketing styles include new colors and button styles, and extend the core typography and whitespace scales. + +### Paths +Here's what you need to know about how the files are structured in both git and in the published npm module: + +* In git, all of the SCSS source files live in the `src/` directory. +* When published, all of the files in `src/` are "hoisted" to the package root so that you can import, say, utilities with: + + ```scss + @import "@primer/css/utilities/index.scss"; + ``` + +* All module interdependencies within Primer CSS are defined as relative imports (e.g. with `../`), so everything should work fine as long as the `@primer/css` directory is in one of your Sass include paths (i.e. `node_modules`). -The top-level `package.json` is not published, but tracks common dependencies for developing Primer, and hosts some useful npm [run-scripts](#scripts). ## Workflow The typical Primer workflow looks something like this: -1. [Install](#install) -2. [Start Storybook](#storybook) -3. Navigate to the module you're working on and modify the SCSS and/or markdown files. -4. Test your changes in Storybook. -5. Push your work to a new branch to test it on Travis and have it reviewed by the Primer "core" team. +1. `npm install` to install the development dependencies. +1. [Start Storybook](#storybook) +1. Navigate to the module you're working on and modify the SCSS and/or markdown files. +1. Test your changes in Storybook. +1. Push your work to a new branch. +1. Request a review from one of the Primer "core" team members. ## Install -Run `npm install` to install the npm dependencies and automatically run link all of the local packages together with `npm run bootstrap`. +Run `npm install` to install the npm dependencies. -### Troubleshooting install problems -If you run into trouble installing, it's always best to ensure that you're starting from a clean slate by running the following from the repository root directory: +## Docs site +The Primer CSS docs are built with React using [Primer Components](https://primer.style/components) and automatically deployed on every push to this repo using our [primer/deploy action](/primer/deploy). You can run the server locally with: ```sh -npm run fresh +npm start ``` -If _that_ gives you problems, then you can try manually deleting everything and starting over: +Then visit http://localhost:3000/css to view the site. -``` -rm -rf node_modules -rm -f package-lock.json */*/package-lock.json -npm install -``` +:rotating_light: **Warning:** Next.js has a [long-running issue](https://github.com/zeit/next.js/issues/1189) with trailing slashes in URLs. Avoid visiting `http://localhost:3000/` if possible, as this may cause your development server to fail in less-than-graceful ways. -**You may need to do this whenever switching between branches with different dependencies, submodules, or versions of Node and/or npm.** The Primer core team generally uses the latest major version of Node (10 as of this writing), but our CI tests run Node 8 and npm 6. You can check which versions you're running with: - -```sh -npm --version -node --version -``` +### TODO +* Document URL tests +* Document how the sync script works ## Storybook -Run `npm start` to start up [Storybook], then visit [localhost:3000](http://localhost:3000) to test your work. By default, all `html` code blocks of all `*.md` files in each module will be rendered as stories and listed under the module's name in the left-hand nav. File changes should trigger live reload automatically after a brief delay. +To borrow a [metaphor from Brad Frost](http://bradfrost.com/blog/post/the-workshop-and-the-storefront/), the [docs site](#docs-site) is Primer CSS's storefront, and [Storybook] is its workshop. + +Our Storybook setup allows you to view every HTML code block in Primer CSS's Markdown docs in isolation. To get started, run the Storybook server with: + +```sh +npm run start-storybook +``` + +Then visit http://localhost:8000 to test your work. + +### Code blocks +All `html` fenced code blocks in `src/**/*.md` will be rendered as stories and listed under the relevant module's name in the left-hand nav. File changes should trigger a live reload automatically (after a brief delay). If the package you're working on has a `stories.js`, it probably includes a snippet like this: @@ -65,8 +85,9 @@ npm run ``` +[@primer/css]: https://www.npmjs.com/package/@primer/css [monorepo]: https://github.com/babel/babel/blob/master/doc/design/monorepo.md -[Lerna]: https://github.com/lerna/lerna [run-scripts]: https://docs.npmjs.com/cli/run-script [Storybook]: https://storybook.js.org/ +[npm]: https://www.npmjs.com/ [npx]: https://www.npmjs.com/package/npx