primer/css
1
1
Fork 0
mirror of https://github.com/primer/css.git synced 2024-11-22 19:01:02 +03:00
Code Issues Projects Releases Wiki Activity

docs: update DEVELOP.md with new workflow

Browse Source
This commit is contained in:
Shawn Allen 2019-02-08 16:34:37 -08:00 committed by GitHub
parent 9b3f4e206d
commit 2812ba3c56
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
DEVELOP.md
View File

@ -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