From 8c86114dca6c26c45ab8f116c251c7c3081e107f Mon Sep 17 00:00:00 2001 From: palantir-team Date: Thu, 14 Apr 2016 16:22:05 -0500 Subject: [PATCH 1/6] minor tweaks to current documentation based on setup work --- README.md | 23 +++++++++++++++-------- docs/CONTRIBUTING.md | 4 ++-- docs/LINTERS.md | 4 +++- 3 files changed, 20 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 502e6d6..59ea68d 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,24 @@ # Butler -The beginnings of a Sculpin-based style guide creation tool. +A tool to automate front-end development tasks and streamline prototyping. ## Dependencies 1. NodeJS 1. To intall NodeJS using Homebrew run `brew install node` 1. [Sculpin](https://sculpin.io/getstarted/) - 1. `curl -O https://download.sculpin.io/sculpin.phar` - 2. `chmod +x sculpin.phar` - 3. `mv sculpin.phar sculpin` or if you are using vagrant run `sudo -H mv sculpin.phar /bin/sculpin` and skip step 4 - 4. `mv sculpin ~/bin/` + + By default Butler expects your project to include Sculpin as a Composer dependency. + You can change this by updating the `defaults.sculpin_run` setting. If you're using a global Sculpin install the `defaults.sculpin_run` variable should be set to `sculpin`. ## Add Butler to a project 1. If the project does not already have npm dependencies run `npm init` to create a `package.json` file 1. Add Butler as a dependency by running `npm install --save palantirnet/butler` + + When Butler is installing it will ask for the GitHub repository for your project. Please provide the HTTPS link for the project repository. + Example: `https://github.com/palantirnet/[project].git` + Butler will use this information to know where to deploy the styleguide to. + + During this step Butler will create a `butler.defaults.js` file in your project's `conf` directory. This will set the project defaults for Butler. 1. Duplicate `STYLEGUIDE_TEMPLATE`, rename it `styleguide`, and add it to the project's root directory @@ -29,9 +34,9 @@ The beginnings of a Sculpin-based style guide creation tool. 1. Run `npm run butler` and begin developing normally -1. Navigate to `localhost:8000` or `[project].local:8000` in your browser to see the styleguide +1. Navigate to `http://localhost:8000/` or `http://[project].local:8000/` in your browser to see the styleguide -1. Add `node_modules` to your project's `.gitignore` file and commit your project's new `package.json` +1. Add `node_modules` to your project's `.gitignore` file and commit your project's new `package.json` and `conf/butler.defaults.js` ## What does this Butler do * `npm run butler` @@ -44,7 +49,9 @@ The beginnings of a Sculpin-based style guide creation tool. * `npm run deploy` - This is a task to deploy the static styleguide to GitHub pages. It will deploy to `gh-pages` branch of the repo defined in the `config/paths.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". *Note: When you are deploying, Butler will ask you for your github credentials multiple times. Enter your own github credentials as prompted.* + This is a task to deploy the static styleguide to GitHub pages. It will deploy to `gh-pages` branch of the repo defined in the `config/paths.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". + + *Note: When you are deploying, Butler will ask you for your GitHub credentials atleast once, possibly multiple times. Enter your own github credentials as prompted.* ## Making Changes to Butler Please feel free to change/extend/break this Gulpfile to fit the specific needs of the project. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ad965db..9414fb6 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -14,9 +14,9 @@ As a major part of the Palantir Tool Chain, this repository should be continuall 1. Modifications to the default tool chain should be reviewed during Sprint Retrospectives. 1. If those modifications are found valuable to the Palantir tool chain as a whole, they should be brought up as a topic at bi-weekly DEFEND meetings. -1. Such meetings will be used as an open forum for debate and/or voting on the issue. +1. Such meetings will be used as an open forum for debate and/or vote on the issue. 1. Should the issue be approved by DEFEND, one would create an PR against this repository (following the above stated standards) to incorporate the work into the base toolchain. -1. PRs are eligible to be merged once when there is consensus and approval from a Senior Designer and Senior Front End Developer in the case of changes to HTML/CSS/JS, and in the case of changes to Butler, it requires approval from Lauren and Ryan. +1. PRs are eligible to be merged once when there is consensus and approval from a Senior Designer and Senior Front-End Developer. Issue, PR and Commit Guidelines below generally followed those outlined in the [documentation repo](https://github.com/palantirnet/development_documentation/blob/master/CONTRIBUTING.md) diff --git a/docs/LINTERS.md b/docs/LINTERS.md index 7342773..a83faa9 100644 --- a/docs/LINTERS.md +++ b/docs/LINTERS.md @@ -2,7 +2,7 @@ This document goes over the linting functionality included in Butler and how it can be ignored or extended for project use. ## Stylelint -Butler runs stylelint as a PostCSS command that ensures that we are writing quality styles. +Butler runs stylelint as a PostCSS command that ensures that we are writing quality styles. Butler will automatically lint as it compiles. As a designer or developer, you will see warnings and errors in the Terminal as they are found by Butler. Default style lint configuration can be found at `butler/config/linters/stylelint.config.json`. It is based on a few defaults that we should be matching in our CSS. @@ -23,4 +23,6 @@ Butler incorporates the [stylelint-selector-bem-pattern plugin](https://github.c .MyComponent-other {} ```` +There is an example class in Butler's `styles.scss`. It is there for example only, to show what _NOT_ to do for class names and what comments _to do_ if you want the linter to check class names. + You can read more documentation on how the selector linter works and how to customize it [here](https://github.com/postcss/postcss-bem-linter). \ No newline at end of file From 4347bf8988a1354986c363b4de0377a2ce01ed06 Mon Sep 17 00:00:00 2001 From: palantir-team Date: Thu, 14 Apr 2016 16:44:17 -0500 Subject: [PATCH 2/6] include note on environment configuration for sculpin --- README.md | 10 ++++++++-- config/butler.defaults.js | 3 ++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 59ea68d..fd4eca0 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,9 @@ A tool to automate front-end development tasks and streamline prototyping. 1. Add Butler as a dependency by running `npm install --save palantirnet/butler` When Butler is installing it will ask for the GitHub repository for your project. Please provide the HTTPS link for the project repository. + Example: `https://github.com/palantirnet/[project].git` + Butler will use this information to know where to deploy the styleguide to. During this step Butler will create a `butler.defaults.js` file in your project's `conf` directory. This will set the project defaults for Butler. @@ -49,9 +51,13 @@ A tool to automate front-end development tasks and streamline prototyping. * `npm run deploy` - This is a task to deploy the static styleguide to GitHub pages. It will deploy to `gh-pages` branch of the repo defined in the `config/paths.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". + This is a task to deploy the static styleguide to GitHub pages. + + Butler will build a Sculpin production artifact to `styleguide/output_prod` and deploy the production artifact to `gh-pages` branch of the repo defined in the `conf/butler.defaults.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". + + You may want to create a `sculpin_site_prod.yml` to define the site URL once deployed. You can find out more information about environment aware configuration for Sculpin [here](https://sculpin.io/documentation/configuration/). - *Note: When you are deploying, Butler will ask you for your GitHub credentials atleast once, possibly multiple times. Enter your own github credentials as prompted.* + *Note: When you are deploying, Butler will ask you for your GitHub credentials at least once, possibly multiple times. Enter your own GitHub credentials as prompted.* ## Making Changes to Butler Please feel free to change/extend/break this Gulpfile to fit the specific needs of the project. diff --git a/config/butler.defaults.js b/config/butler.defaults.js index 98cb9f4..1c7e700 100644 --- a/config/butler.defaults.js +++ b/config/butler.defaults.js @@ -30,7 +30,8 @@ defaults.stylelint = { configFile: 'config/linters/stylelint.config.json' }; // Deploy defaults // point to the correct repo & include deploy message defaults.deploy = { - remoteUrl: defaults.repo + remoteUrl: defaults.repo, + message: 'Updated with Butler - [timestamp]' }; module.exports = defaults; From bbf8bffa2d89d94b657f781f9ecaefb59777a781 Mon Sep 17 00:00:00 2001 From: Bec White Date: Fri, 15 Apr 2016 16:02:55 -0500 Subject: [PATCH 3/6] Edited sentences for flow; tweaked whitespace and formatting. --- README.md | 90 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 47 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index fd4eca0..77be0a8 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,74 @@ # Butler -A tool to automate front-end development tasks and streamline prototyping. + +A tool to automate front-end development tasks and streamline prototyping. ## Dependencies -1. NodeJS - 1. To intall NodeJS using Homebrew run `brew install node` -1. [Sculpin](https://sculpin.io/getstarted/) - - By default Butler expects your project to include Sculpin as a Composer dependency. - You can change this by updating the `defaults.sculpin_run` setting. If you're using a global Sculpin install the `defaults.sculpin_run` variable should be set to `sculpin`. + +* **NodeJS** + 1. If you are running Butler on your local machine, you can install using Homebrew: `brew install node` + 1. If you are running Butler on a Vagrant, our default VM comes with node installed. +* **Sculpin** + 1. Butler expects Sculpin to be included in your project using `composer`. Make sure you've run `composer install` in your project before running Butler. + 1. If you would like to use globally-installed Sculpin instead: first, follow [Sculpin's installation guide](https://sculpin.io/getstarted/); then configure Butler to use it by setting `defaults.sculpin_run = 'sculpin';` in your project's `conf/butler.defaults.js` file. ## Add Butler to a project -1. If the project does not already have npm dependencies run `npm init` to create a `package.json` file -1. Add Butler as a dependency by running `npm install --save palantirnet/butler` - - When Butler is installing it will ask for the GitHub repository for your project. Please provide the HTTPS link for the project repository. - - Example: `https://github.com/palantirnet/[project].git` - - Butler will use this information to know where to deploy the styleguide to. - - During this step Butler will create a `butler.defaults.js` file in your project's `conf` directory. This will set the project defaults for Butler. +1. If the project does not already have npm dependencies, run `npm init` to create a `package.json` file +1. Add Butler as a dependency: `npm install --save palantirnet/butler` + + When Butler is first installed, it will ask for the location of your project's GitHub repository. Please provide the HTTPS link for the project repository, e.g. `https://github.com/palantirnet/[project].git`; Butler will use this information to deploy the styleguide. + + Butler will store this information in a project-specific configuration file at `conf/butler.defaults.js`. -1. Duplicate `STYLEGUIDE_TEMPLATE`, rename it `styleguide`, and add it to the project's root directory +1. Copy the `STYLEGUIDE_TEMPLATE` to your project's root directory and rename it `styleguide`. This name is required. +1. Add the following code to your project's `package.json`: -1. Add the following code to your project's `package.json` + ```` + "scripts": { + "butler": "gulp --gulpfile node_modules/butler/gulpfile.js develop", + "linting": "gulp --gulpfile node_modules/butler/gulpfile.js test", + "deploy": "gulp --gulpfile node_modules/butler/gulpfile.js deploy" + }, + ```` +1. Add the `node_modules` directory to your project's .gitignore +1. Commit Butler's changes to your project: + * `.gitignore` + * `conf/butler.defaults.js` + * `package.json` + * `styleguide/` +1. When you're ready to start working on code, run `npm run butler` +1. The styleguide can be found on port 8000: + * `http://[project].local:8000` if you're running Butler on a Vagrant + * [http://localhost:8000](http://localhost:8000) if you're developing locally -```` -"scripts": { - "butler": "gulp --gulpfile node_modules/butler/gulpfile.js develop", - "linting": "gulp --gulpfile node_modules/butler/gulpfile.js test", - "deploy": "gulp --gulpfile node_modules/butler/gulpfile.js deploy" -}, -```` +## What does this Butler do? -1. Run `npm run butler` and begin developing normally +* `npm run butler` -1. Navigate to `http://localhost:8000/` or `http://[project].local:8000/` in your browser to see the styleguide + This is the default task. This will watch your sass/sculpin files for changes and compile/build accordingly. It will also flag any sass linting errors before compiling. It will output CSS that has been been minified and optimized. -1. Add `node_modules` to your project's `.gitignore` file and commit your project's new `package.json` and `conf/butler.defaults.js` +* `npm run linting` -## What does this Butler do -* `npm run butler` - - This is the default task. This will watch your sass/sculpin files for changes and compile/build accordingly. It will also flag any sass linting errors before compiling. It will output CSS that has been been minified and optimized. + This is the testing task it will run linters as their own tasks. To learn more about configuring and customizing the linters for Butler check the [linters documentation](/docs/LINTERS.md). -* `npm run linting` +* `npm run deploy` - This is the testing task it will run linters as their own tasks. To learn more about configuring and customizing the linters for Butler check the [linters documentation](/docs/LINTERS.md). + This is a task to deploy the static styleguide to GitHub pages. -* `npm run deploy` + Butler will build a Sculpin production artifact to `styleguide/output_prod` and deploy the production artifact to `gh-pages` branch of the repo defined in the `conf/butler.defaults.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". - This is a task to deploy the static styleguide to GitHub pages. - - Butler will build a Sculpin production artifact to `styleguide/output_prod` and deploy the production artifact to `gh-pages` branch of the repo defined in the `conf/butler.defaults.js`. Each commit for this process will default to the message: "Updated with Butler - [timestamp]". - - You may want to create a `sculpin_site_prod.yml` to define the site URL once deployed. You can find out more information about environment aware configuration for Sculpin [here](https://sculpin.io/documentation/configuration/). - - *Note: When you are deploying, Butler will ask you for your GitHub credentials at least once, possibly multiple times. Enter your own GitHub credentials as prompted.* + You may want to create a `sculpin_site_prod.yml` to define the site URL once deployed. You can find out more information about environment aware configuration for Sculpin [here](https://sculpin.io/documentation/configuration/). + + *Note: When you are deploying, Butler will ask you for your GitHub credentials at least once, possibly multiple times. Enter your own GitHub credentials as prompted.* ## Making Changes to Butler + Please feel free to change/extend/break this Gulpfile to fit the specific needs of the project. For more information on contributing to this project check the [contributing documentation](/docs/CONTRIBUTING.md). ## Troubleshooting + For immediate concerns, if you have comments/questions/concerns about working with this please talk to Lauren. To file bug or feature requests, please use the GitHub issue queue for this repository. You can see more about our Issue Guidelines in the [contributing documentation](/docs/CONTRIBUTING.md). From 1187792c3d787a81477b04adbdecbc87fecb4417 Mon Sep 17 00:00:00 2001 From: palantir-team Date: Fri, 15 Apr 2016 17:12:15 -0500 Subject: [PATCH 4/6] update documentation around changing and customizing --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 77be0a8..f3640e0 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,9 @@ A tool to automate front-end development tasks and streamline prototyping. ## Making Changes to Butler -Please feel free to change/extend/break this Gulpfile to fit the specific needs of the project. +You can modify Butler defaults on a per project basis by editing the `conf/butler.defaults.js` within your projects. + +If you would like to see additional functionality added to Butler please either create a PR or a GitHub issue, outlining the needs and requirements. For more information on contributing to this project check the [contributing documentation](/docs/CONTRIBUTING.md). From 19646ed9f2d1a02f2a1c0cc2bd3eb7e30c665b58 Mon Sep 17 00:00:00 2001 From: Bec White Date: Fri, 15 Apr 2016 17:18:30 -0500 Subject: [PATCH 5/6] Remove redundant section. --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index f3640e0..17dcc38 100644 --- a/README.md +++ b/README.md @@ -61,14 +61,6 @@ A tool to automate front-end development tasks and streamline prototyping. *Note: When you are deploying, Butler will ask you for your GitHub credentials at least once, possibly multiple times. Enter your own GitHub credentials as prompted.* -## Making Changes to Butler - -You can modify Butler defaults on a per project basis by editing the `conf/butler.defaults.js` within your projects. - -If you would like to see additional functionality added to Butler please either create a PR or a GitHub issue, outlining the needs and requirements. - -For more information on contributing to this project check the [contributing documentation](/docs/CONTRIBUTING.md). - ## Troubleshooting For immediate concerns, if you have comments/questions/concerns about working with this please talk to Lauren. From c53a79bc9e407f1027c8a329685c0b0058546e50 Mon Sep 17 00:00:00 2001 From: Bec White Date: Fri, 15 Apr 2016 18:21:52 -0500 Subject: [PATCH 6/6] Specify scripts using Butler's own gulp, and allow running butler directly. --- README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 17dcc38..de37853 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,10 @@ A tool to automate front-end development tasks and streamline prototyping. ```` "scripts": { - "butler": "gulp --gulpfile node_modules/butler/gulpfile.js develop", - "linting": "gulp --gulpfile node_modules/butler/gulpfile.js test", - "deploy": "gulp --gulpfile node_modules/butler/gulpfile.js deploy" + "butler": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js", + "develop": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js develop", + "linting": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js test", + "deploy": "node_modules/butler/node_modules/.bin/gulp --gulpfile node_modules/butler/Gulpfile.js deploy" }, ```` 1. Add the `node_modules` directory to your project's .gitignore @@ -47,6 +48,10 @@ A tool to automate front-end development tasks and streamline prototyping. This is the default task. This will watch your sass/sculpin files for changes and compile/build accordingly. It will also flag any sass linting errors before compiling. It will output CSS that has been been minified and optimized. +* `npm run butler -- sass` + + Just compile the sass. You can also use this syntax to run any task from the Gulpfile. + * `npm run linting` This is the testing task it will run linters as their own tasks. To learn more about configuring and customizing the linters for Butler check the [linters documentation](/docs/LINTERS.md).