Merge pull request #222 from puppetlabs/update-contributing-docs

Update contributing docs

Author: vine77

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 <[email protected]>.
 
-- 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 [email protected]: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/<package-name>` 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/<package-name>` 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.
+
+| <img src="https://imgs.xkcd.com/comics/git_commit.png" alt="xkcd comic about commit messages"/> |
+| ------------- |
+| <p align="center">Don't do this</p> |
+
+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 [email protected]:puppetlabs/design-system.git master

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",

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",

packages/design-system-website/README.md

@@ -8,21 +8,15 @@ 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
 
 See the changelog for each package, like react-components' [CHANGELOG.md](https://github.com/puppetlabs/design-system/blob/master/packages/react-components/CHANGELOG.md).
 
 ### 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
 

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

packages/react-components/CONTRIBUTING.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):
 

packages/react-components/README.md

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