diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67d817b71..a216b7551 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,10 +2,6 @@ The Puppet Design System is a cross-functional team effort across Puppet with shared ownership where contributions are encouraged. Though designed for and maintained by Puppet, outside PRs are welcome. A good place to start is by visiting [#team-design-system](https://puppet.slack.com/messages/CFFECRQAY) in Puppet's internal Slack or contacting . -- See the general [Consumption and Contribution](https://github.com/puppetlabs/design-system/wiki/Consumption-and-Contribution) principles on the wiki. -- See individual CONTRIBUTING.md files for specific packages: - - react-components: [packages/react-components/CONTRIBUTING.md](packages/react-components/CONTRIBUTING.md) - ## Install Clone the design-system monorepo: @@ -14,7 +10,7 @@ Clone the design-system monorepo: git clone git@github.com:puppetlabs/design-system.git && cd design-system ``` -Run `npm install` in the root of the design-system to install all package dependencies (which uses [Lerna](https://lerna.js.org/) to link local packages together and hoist duplicate dependencies up to the top directory to reduce install time): +We recommend the latest LTS version of Node.js. Run `npm install` in the root of the design-system to install all package dependencies (which uses [Lerna](https://lerna.js.org/) to link local packages together and hoist duplicate dependencies up to the top directory to reduce install time): ```sh npm install @@ -30,30 +26,42 @@ npm start ## Local development -To develop locally using a separate app that consumes a design-system package, you can run `npm link` in a particular package subfolder and `npm link @puppet/` in the consuming app. See each individual package's own README.md; some have `npm run watch` commands to rebuild on change. +To develop locally using a separate app that consumes a design-system package: + +1. Run `npx lerna run link` (which will run `npm link` in consumable packages). +2. Run `npm link @puppet/` in the consuming app. +3. Run `npx lerna run --parallel watch` to rebuild packages on change ( or just `npm run watch` in the desired package). ## Testing -You can run `npm test` in a package subfolder or `npm test` in the top folder to test all packages. +Run `npm test` in the top folder to test all packages, or `npm test` in the desired package. You can also run `npm lint` to check for code formatting errors or `npm format` to attempt to automatically fix them. ## Pull requests Put up a PR for the design-system repo that follows these guidelines: -- Granularity: Make commits of logical units (ideally with each commit passing tests). -- Tense: Use the imperative present tense (e.g. "Change", not "Changed" or "Changes") to describe what changed from the consumer's perspective in the commit summary (with any extra details or motivation in the commit body). -- Ticket: Associate with the Jira issue by adding the issue key to the commit body and, if it resolves the ticket, use the "PDS-123 #resolve" syntax to resolve the issue. -- Fork: For the Jira issue to be resolved on merging rather than opening the PR (with the above syntax), the PR can be opened from a branch on your fork of the design-system repo. +- Granularity: Make commits of logical units (ideally with each commit passing tests, and formatting and refactoring in separate commits). +- Commit summary: The first line should be no more than 72 characters (with any extra details or motivation in the commit body). +- Tense: Use the imperative present tense (e.g. "Add feature", not "Added feature") to describe what changed from the consumer's perspective in the commit summary. +- Changelog: Add a line about your change to the package's CHANGELOG.md file. + +| xkcd comic about commit messages | +| ------------- | +|

Don't do this

| + +See more guidelines for contributors and maintainers in the [Principles, Patterns, and Guidelines](principles-patterns-guidelines.md) doc. ## Publishing +New versions are currently released by maintainers using `npm run publish`. Please collaborate with the team to release a new version. (Note: This process will likely be replaced with automated releases on push to master.) + This project currently uses Lerna's independent mode, so the following command will prompt you to select a new version for any packages that have changed since the last version tags. WARNING: this command results in a git push to your `origin` remote. ```sh npm run publish ``` -If `origin` was not puppetlabs/design-system, push the "Publish" commit that created, along with version tags, to the upstream repo: +If `origin` was not puppetlabs/design-system, push the "Publish" commit the above command created, along with version tags, to the upstream repo: ```sh git push --follow-tags git@github.com:puppetlabs/design-system.git master diff --git a/package.json b/package.json index 2c1e17c74..ea79bdacd 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,8 @@ "postinstall": "lerna bootstrap", "test": "lerna run lint && lerna run test", "start": "cd packages/design-system-website && npm start", - "styleguide:build": "cd packages/design-system-website && npm run styleguide:build" + "styleguide:build": "cd packages/design-system-website && npm run styleguide:build", + "publish": "lerna publish" }, "devDependencies": { "@babel/preset-stage-2": "^7.0.0", diff --git a/packages/data-grid/package.json b/packages/data-grid/package.json index 714f898de..3e4ab8123 100644 --- a/packages/data-grid/package.json +++ b/packages/data-grid/package.json @@ -5,6 +5,7 @@ "license": "Apache-2.0", "main": "dist/index.js", "scripts": { + "link": "npm link", "build": "webpack", "watch": "webpack --watch", "watch:dev": "webpack --watch --env.development", diff --git a/packages/design-system-website/README.md b/packages/design-system-website/README.md index 4f1e0a1f4..2e555413c 100644 --- a/packages/design-system-website/README.md +++ b/packages/design-system-website/README.md @@ -8,11 +8,7 @@ For background, see [Puppet Design System](https://confluence.puppetlabs.com/dis ### Getting started -**Designers** should download and install the [Sketch library](https://github.com/puppetlabs/design-system/blob/master/packages/design-assets/puppet-ui-library.sketch). Instructions for [installation and receiving updates](https://confluence.puppetlabs.com/display/UXT/Design+System+Sketch+library) are on Confluence. - -**Developers** can get started by cloning the repo and following the [quickstart guide](https://github.com/puppetlabs/design-system). - -**Writers** should start with the [foundation on content writing](#/Foundations/Content%20Writing) or the [writing guidelines on Confluence](https://confluence.puppetlabs.com/display/Writing/Puppet+content+style+guide). These are helpful for anyone creating content, from full pages to micro-copy. +Get started by cloning the repo and following the [quickstart guide](https://github.com/puppetlabs/design-system). ### Release notes @@ -20,9 +16,7 @@ See the changelog for each package, like react-components' [CHANGELOG.md](https: ### Contribute -The Puppet Design System is a cross-functional team effort with shared ownership. Contributions are both welcome and encouraged. We have written a [best-practices guide](https://github.com/puppetlabs/design-system/wiki) to help you get started. - -Developers should start with the the [CONTRIBUTING.md](https://github.com/puppetlabs/design-system/blob/master/CONTRIBUTING.md) in the repo. Designers should reference the [design criteria for adding symbols and styles](https://github.com/puppetlabs/design-system/wiki/Design-criteria) to the Sketch library. +The Puppet Design System is a cross-functional team effort with shared ownership. Contributions are both welcome and encouraged. Please read our [CONTRIBUTING.md](https://github.com/puppetlabs/design-system/blob/master/CONTRIBUTING.md) guide (and [Designing](#/Foundations/Designing) guide if applicable). ### Feedback diff --git a/packages/design-system-website/foundations/Iconography.md b/packages/design-system-website/foundations/Iconography.md index 09537a3a1..17bcc00d9 100644 --- a/packages/design-system-website/foundations/Iconography.md +++ b/packages/design-system-website/foundations/Iconography.md @@ -75,8 +75,7 @@ The vast majority of icons do not provide enough information by themselves for a ## Naming conventions -The same name should be used between the Sketch library and the component library. -Names should be prioritized in descending order: +The same name should be used between the Figma library and the component library. Names should be prioritized in descending order: 1. **Object noun** - eg. Diamond, not Quality. Pencil, not Edit. 2. **Verb**. Describe the action, if the noun would be less clear. - eg. Undo, not Curved-Arrow-Left. @@ -127,7 +126,7 @@ Test that the icon: - Scales correctly - Accepts style changes -- Name corresponds with Sketch library and exported SVG +- Name corresponds with Figma library and exported SVG - Is added to documentation ## Related diff --git a/packages/react-components/CONTRIBUTING.md b/packages/react-components/CONTRIBUTING.md deleted file mode 100644 index b4efd7fcd..000000000 --- a/packages/react-components/CONTRIBUTING.md +++ /dev/null @@ -1,166 +0,0 @@ -# Contributing to Puppet React Components - -Thanks for your interest in contributing! This document outlines how to submit a -bug or request an enhancement, set up your development environment, open a pull -request, deploying new versions, and reviewing code. - -## Filing a bug or enhancement - -We currently track bugs and enhancements in the "Puppet Design System" Jira -project: - -You're encouraged to open a ticket before you begin developing. This helps us -avoid duplicated work and often serves as a chance for others to weigh in. - -## Setting up your development environment - -We use Node.js and npm scripts for our build tooling. Our CI server runs Node -LTS, which we recommend you do as well. You can install versions of Node -using [nvm](https://github.com/creationix/nvm). - -Once you've installed Node, install the dependencies for this project with: - -``` -npm install -``` - -UI Components includes a styleguide that allows us to test components in -isolation. It's built with [React Styleguidist](https://github.com/styleguidist/react-styleguidist), -and content is sourced from a Markdown file living next to each respective -component. - -**To start the styleguide for local development:** - -1. Run `npm start`. -2. Open the [styleguide](http://localhost:6060) at http://localhost:6060. - -**To build the library as a module and watch for changes:** - -1. If you haven't already done so, run `npm link` in this directory. -2. Run `npm run watch` to build the module and rebuild on any change. -3. For any project in which UI Components is a dependency, you can link UI - Components to see your changes reflected in the parent. In the parent project, - run `npm link @puppet/react-components`. Make sure you're using the same - version of Node.js in both projects. - -## Testing and linting - -We use Mocha, Chai, and Enzyme for testing this project. We use ESLint for -linting our javascript, which has a configuration based of [Airbnb's](https://www.npmjs.com/package/eslint-config-airbnb). -Additionally, we lint our SCSS using StyleLint. - -We've written up some of our best practices we use while testing our React -projects [here](https://reflect.io/blog/js-testing-mocha-chai-enzyme/). - -To run tests: - -``` -npm test -``` - -To lint Javascript: - -``` -npm run js-lint -``` - -To lint Scss: - -``` -npm run scss-lint -``` - -## Commits - -![](https://imgs.xkcd.com/comics/git_commit.png) - -- The commit summary (first line) should: - - Be no more than 72 characters, - - Use imperative present tense ("fix", not "fixed" or "fixes"), and - - Include Jira ticket if applicable (e.g. "(PDS-XXX) Rest of message") -- A commit body may be added when the commit is sufficiently complex (to include motivation for the change, contrast with the previous behavior, etc.) -- Commits should be of appropriate granularity (and keep formatting and refactoring in separate commits) - -## Rebasing vs merging - -When you are the sole contributor on a branch it is prefered that you rebase the parent branch to keep -a clean git history. However, when working on a branch with multiple people it's recommended that you -always merge the parent into the child. This prevents the other engineers from having to blow out their -local branch and reduces the risk of losing commits. - -## Opening a pull request - -You've built a new feature, fixed a bug, or maybe you fixed a typo in this -document. Whatever you're planning on contributing, the next step is to open a -pull request and have your changes changes reviewed. - -Before doing so, here's a small checklist to run through: - -- [ ] Have I written tests where appropriate? -- [ ] Have my tests and linter passed locally? -- [ ] Have I added my change to CHANGELOG.md? - -If the answer to these is "yes", you're ready to go! Once you've pushed your -branch up to Github, you're ready to open a pull request. - -- Open your Pull Request against the development branch. -- You may be asked to make stylistic changes to align your contribution with - existing code, add tests, or any other requests. -- The reviewer will merge your pull request and delete your branch once it has - been approved. You're more than welcome to merge as well. - -If you have any questions about this process, please reach out to the -maintainers. Again, thank you for the contribution! - -## Releasing a new version - -New versions are currently released by maintainers using `lerna publish`. Please collaborate with the team in [#team-design-system](https://puppet.slack.com/messages/CFFECRQAY) to release a new version. (Note: This process will likely be replaced with automated releases on push to master.) - - - -## Reviewing pull requests - -Here's some things to look for when reviewing pull requests: - -- Is the code readable? Does it make sense? Can you decipher the intent? -- Are there an appropriate amount of tests? Can you decipher the intent of the - tests? -- Is the code style in line with the rest of the file? The project? The team? -- Are there inline comments where necessary? - -Good reviewers are respectful and try to understand the intent of the -contributor. - -Thanks! diff --git a/packages/react-components/README.md b/packages/react-components/README.md index 1c75bd563..880a1aca5 100644 --- a/packages/react-components/README.md +++ b/packages/react-components/README.md @@ -20,7 +20,7 @@ npm install @puppet/react-components ## Setup -### Webpack (without Create React App) +### With webpack (without Create React App) React Components utilizes Calibre and Open Sans. In order for Calibre to load, you will need to process the react-components scss with Webpack. This has currently been tested with webpack 4 using css-loader, sass-loader, file-loader, resolve-url-loader, and mini-css-extract-plugin. The following is an example configuration for a consuming application: @@ -66,7 +66,7 @@ const common = { }; ``` -### Create React App +### With Create React App (CRA) If you are using CRA with [react-app-rewired](https://github.com/timarney/react-app-rewired) (after following their [instructions](https://github.com/timarney/react-app-rewired/blob/master/README.md#how-to-rewire-your-create-react-app-project) for switching from react-scripts to react-app-rewired in package.json), you can use this included rewire instead (after adding `resolve-url-loader` to devDependencies): diff --git a/packages/react-components/package.json b/packages/react-components/package.json index 40a152013..9fb0e0572 100644 --- a/packages/react-components/package.json +++ b/packages/react-components/package.json @@ -5,6 +5,7 @@ "license": "Apache-2.0", "main": "build/library.js", "scripts": { + "link": "npm link", "analyze": "webpack --config webpack.analyze.config.js", "prebuild": "rimraf build", "build": "NODE_ENV=production webpack", diff --git a/packages/react-components/pds-1.0-migration.md b/packages/react-components/pds-1.0-migration.md deleted file mode 100644 index 6fbb95a34..000000000 --- a/packages/react-components/pds-1.0-migration.md +++ /dev/null @@ -1,83 +0,0 @@ -# PDS 1.0 Component update process - -The goal of our component update process is to align the design primary source (the sketch [styleguide](design/puppet-styleguide.sketch) and accompanying symbols) with the code and accompanying documentation in order to build a complete and self-consistent design system. - -## General principles - -* *Question everything* - if you don't understand what a component or prop is doing and why it's needed in our system, chances are no one else will either. -* *Focus on usability* - how can we make our react components as easy to use as possible? -* *Design intent should be communicated at every layer of the code*: The component APIs and documentation should reflect the intended use as specified in the design system. When handed a mockup built in sketch, it should be immediately clear which component to use, and how to use it. -* *Be minimalistic* - If we can delete a thing (component, prop, etc) without causing problems that's probably the better option. The system will naturally get more complicated over time. - -## Component update checklist - -1. [] Design specifications are finalized and complete - * Review [the styleguide](design/puppet-styleguide.sketch) for design guidelines on the component in question. Look for badges claiming `needs specification` or `needs design` to indicate acknowledged design deficiencies. - * Use [the dependency helpers](https://github.com/puppetlabs/react-component-dependents) to audit current use of the component in question. Keep in mind that the scripts often give a partial answer, you will need to dig in deeper in certain places. - * Sit down with a designer and get answers to the following questions: - - Questions: - - * What is the intended use of this component and do we need it? - * Do we need all of the variations of the component specified in the design guidelines? - * Do the design specifications cover all states? (focus, active, error, etc) - * Do the design specifications cover all variants and uses of the component in current code? - - **Result** A ticket in JIRA specifying the design updates needed in order to finalize the code. -2. [] Component API is finalized and consistent with design specifications - * Audit current code. - * Identify prop options that can be removed. - * In limited and worthwhile cases, use your judgement to identify opportunities to clarify component APIs to make the intended use more clear. -4. [] Component API is consistent with common patterns (below) and relevant patterns established in other components - * This will need to evolve as we get further along. We should be specifying common props such as size and color in a consistent manner. Use your judgement -5. [] Easy accessibility updates are made - * Full accessibility will be hard and will take time, but we should be using this opportunity to get easy wins such as: - * Making sure basic interactive elements have appropriate focus / active states - * Making sure that appropriate html elements are used (for example, `a` tags for links and `button` tags for buttons), making element choice flexible where appropriate with the `as` prop pattern. -6. [] Component use is well documented in styleguidist - * Use comments to describe all props and their use - * Make examples in accompanying markdown files that convey *how* to use a component appropriately, focusing on their intended use in relation to design specifications. - * Organize styleguidist to focus attention on the top-level components (for example, on Menu -7. [] Component style is 100% consistent with design guidelines - * This includes all states where appropriate. - - - ## Common code patterns - - - These patterns are agreed upon and should serve as the north-star, but are somewhat aspirational. Use your judgement to decide when the effort required to standardize patterns outweighs the benefit. - - * Top-level components should accept `className` and `style` props that are propagated down to the appropriate inner element so that the component can be positioned appropriately. - * Prefer enumerated string props over mutually exclusive boolean props. For example, prefer `