From b66efcb25fe256bc914afeedea4cd83ddb2bddea Mon Sep 17 00:00:00 2001 From: Chris Pearce Date: Sun, 26 Apr 2015 08:57:17 +1000 Subject: [PATCH] Main README updates --- README.md | 535 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 452 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 6941a9a..5b8e145 100644 --- a/README.md +++ b/README.md @@ -10,51 +10,67 @@ - [Scally architecture](#scally-architecture) - [Dependencies](#dependencies) - [Installing Scally](#installing-scally) - - [Packages](#packages) - - [Getting the latest version](#getting-the-latest-version) - - [Download by zip](#download-by-zip) + - [Packages](#packages) + - [Git clone](#git-clone) + - [Download by zip](#download-by-zip) - [Setting up a new project](#setting-up-a-new-project) - - [Setting up your master stylesheet](#setting-up-your-master-stylesheet) - - [Master stylesheet overview](#master-stylesheet-overview) - - [Your settings](#your-settings) - - [Scally framework](#scally-framework) - - [Your styles](#your-styles) - - [Example architecture](#example-architecture) + - [Setting up your master stylesheet](#setting-up-your-master-stylesheet) + - [Master stylesheet overview](#master-stylesheet-overview) + - [Your settings](#your-settings) + - [Scally framework](#scally-framework) + - [Your styles](#your-styles) + - [Master stylesheet template](#master-stylesheet-template) + - [Example architecture](#example-architecture) - [Browser support](#browser-support) -- [Linting](#linting) +- [Authoring guidelines](#authoring-guidelines) + - [Linting](#linting) + - [Installation](#installation) + - [Linting rules](#linting-rules) - [Contributing](#contributing) -- [Scally improvements, issues, and questions](#scally-improvements-issues-and-questions) + - [Keep it simple](#keep-it-simple) + - [Submitting code to Scally](#submitting-code-to-scally) + - [Scally GitHub issues](#scally-gitHub-issues) - [Versioning](#versioning) - [Credits](#credits) - [License](#license) -- [Presentations](#presentations) +- [Further documentation](#further-documentation) -**Version 2 is coming in the next few days, in the meantime take a look at the [v2](https://github.com/chris-pearce/scally/tree/v2) branch and it's [CHANGELOG.md](https://github.com/chris-pearce/scally/blob/v2/CHANGELOG.md).** # What is Scally? -Scally is a [Sass](http://sass-lang.com/)-based, [BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/), [OOCSS](http://www.smashingmagazine.com/2011/12/12/an-introduction-to-object-oriented-css-oocss/), responsive ready, CSS framework that provides you with a solid foundation for building reusable UI's quickly. It is a framework focused on scalability and reuse, there when you need it and getting out of your way when you don't. +Scally is a [Sass](http://sass-lang.com/)-based, +[BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/), +[OOCSS](http://www.smashingmagazine.com/2011/12/12/an-introduction-to-object-oriented-css-oocss/), +responsive ready, CSS framework that provides you with a solid foundation for +building reusable UI's quickly. It is a framework focused on scalability and +reuse, there when you need it and getting out of your way when you don't. -Scally is designed to be configurable, only requiring you to bring in the parts you are using, keeping your CSS architecture light weight and scalable. It is unopinionated about design giving you more flexibility than your typical UI toolkit. +Scally is designed to be configurable, only requiring you to bring in the parts +you are using, keeping your CSS architecture light weight and scalable. It is +unopinionated about design giving you more flexibility than your typical UI +toolkit. # Demos -*A website—featuring demos of everything in Scally—is coming soon, in the meantime they're CodePen's that can be looked at but are a work in progress:* +*A website—featuring demos of everything in Scally—is coming soon, in the +meantime they're CodePen's that can be looked at but are a work in progress:* - [Layout](http://codepen.io/chris-pearce/full/jEXNWX/) -- [Utilities](http://s.codepen.io/chris-pearce/full/WbMgMp) +- [Utilities](http://codepen.io/chris-pearce/full/WbMgMp/) # Scally architecture -Scally is broken down into five main sections with each section getting it's own level of specificity meaning each one builds on top of the other in terms of inheritance and CSS' first C; the cascade. Think of them as layers: +Scally is broken down into five main sections with each section getting it's +own level of specificity meaning each one builds on top of the other in terms +of inheritance and CSS' first C; the cascade. Think of them as layers: @@ -71,13 +87,19 @@ The breakdown of these layers from bottom to top (order of their specificity): # Dependencies -- [Ruby](http://rubyinstaller.org/), *if you're using a Mac then Ruby comes pre-installed* +- [Ruby](http://rubyinstaller.org/) (if you're using a Mac then Ruby comes + pre-installed) or [LibSass](http://libsass.org/), one of these is needed to + compile Scally's Sass - [Sass](http://sass-lang.com/install) - [Autoprefixer](https://github.com/postcss/autoprefixer) - >> Autoprefixer parses CSS and adds vendor-prefixed CSS properties using the Can I Use database. + >> Autoprefixer parses CSS and adds vendor-prefixed CSS properties using + the [Can I use](http://caniuse.com/) database. - *We advise you to setup Autoprefixer as part of your build process e.g. if you're using [Grunt](http://gruntjs.com/) then you can create a Grunt task for Autoprefixer using something [like](https://github.com/nDmitry/grunt-autoprefixer)* + *We advise you to setup Autoprefixer as part of your build process e.g. if + you're using [Grunt](http://gruntjs.com/) then you can create a Grunt task + for Autoprefixer using something + [like](https://github.com/nDmitry/grunt-autoprefixer)*. @@ -91,7 +113,10 @@ Scally can be installed as a package with either: - [npm](https://www.npmjs.org/) - [Bower](http://bower.io/) -You'll need [Node.js](http://nodejs.org/) installed to use the npm and Bower packages, more information on installing npm [here](http://blog.npmjs.org/post/85484771375/how-to-install-npm). Once npm is installed you're good to install the Scally npm package by `cd`ing into your project folder (the root is recommended) and running this command: +You'll need [Node.js](http://nodejs.org/) installed to use the npm and Bower +packages, more information on installing npm [here](http://blog.npmjs.org/post/85484771375/how-to-install-npm). +Once npm is installed you're good to install the Scally npm package by `cd`ing +into your project folder (the root is recommended) and running this command: ``` npm install scally @@ -103,7 +128,8 @@ For the Scally Bower package you first need to install Bower via npm like so: npm install -g bower ``` -Then, just like the npm package, you `cd` into your project folder (the root is recommended) and run this command: +Then, just like the npm package, you `cd` into your project folder (the root is +recommended) and run this command: ``` bower install scally @@ -131,36 +157,57 @@ project root └───scally ``` -### Getting the latest version +**N.B.** Scally should never be edited or added too directly. If you ever make +changes directly in Scally you will not be able to seamlessly update your +version of Scally to the latest version. -Once installed you can always get the latest version of Scally by running the following commands: +*This is a very simple overview of npm and Bower so if you're new to them then +please take the time to read up on them.* -- **npm:** `npm update scally` -- **Bower:** `bower update scally` +## Git clone -**N.B.** Scally should never be edited or added too directly. If you ever make changes directly in Scally you will not be able to seamlessly update your version of Scally to the latest version. +You can install Scally by using the `git clone` command by `cd`ing into the +root of your workspace folder and running this command: -*This is a very simple overview of npm and Bower so if you're new to them then please take the time to read up on them.* +``` +git clone git@github.com:chris-pearce/scally.git +``` + +If you don't want to use the SSH clone URL GitHub also offers: + +- [HTTPS](https://github.com/chris-pearce/scally.git) +- [Subversion](https://github.com/chris-pearce/scally) ## Download by zip -You can install Scally via the [**Download by zip**](https://github.com/chris-pearce/scally/archive/master.zip) option however it's advised to use a package manager like npm or Bower to handle your third-party dependencies. +You can install Scally via the [**Download by zip**](https://github.com/chris-pearce/scally/archive/master.zip) +option which is part of the Scally GitHub interface. + +**It's advised to use a package manager like npm or Bower to handle your +third-party dependencies.** # Setting up a new project ## Setting up your master stylesheet -Once you have installed Scally you will need to create a master Sass stylesheet called `style.scss`, or whatever you want to name it, but for the purpose of this document `style.scss` will be the expected name. Then read the next section: [Master stylesheet overview](#master-stylesheet-overview). +Once you have installed Scally you will need to create a master Sass stylesheet +called `style.scss`, or whatever you want to name it, but for the purpose of +this document `style.scss` will be the expected name. Then read the next +section: [Master stylesheet overview](#master-stylesheet-overview). This file will live at the root of the folder where you keep all of your CSS. -This will be your master stylesheet and is what you will link too from your HTML head, once compiled that is, you can run a basic Sass watch command to compile your Sass, like this: +This will be your master stylesheet and is what you will link too from your HTML +head, once compiled that is, you can run a basic Sass watch command to compile +your Sass, like this: ``` sass --watch style.scss:style.css ``` -But for most projects your Sass will be compiling as part of your build process e.g. if you're using [Grunt](http://gruntjs.com/) then you can create a Grunt task to compile Sass using something [like](https://github.com/gruntjs/grunt-contrib-sass). +But for most projects your Sass will be compiling as part of your build process +e.g. if you're using [Grunt](http://gruntjs.com/) then you can create a Grunt +task to compile Sass using something [like](https://github.com/gruntjs/grunt-contrib-sass). Then add a reference to the compiled master stylesheet in your HTML head: @@ -168,21 +215,28 @@ Then add a reference to the compiled master stylesheet in your HTML head: ``` -This master stylesheet is designed to pull in everything from Scally–however only the **Core** section is mandatory–plus your project-specific styles and compile down to a single css file. +This master stylesheet is designed to pull in everything from Scally–however +only the **Core** section is mandatory–plus your project-specific styles and +compile down to a single css file. ## Master stylesheet overview Your master stylesheet is split into three main sections: -1. [**Your settings.**](#your-settings) All of your project-specific settings in the form of Sass variables. -2. [**Scally framework.**](#scally-framework) The entire Scally framework including your overrides. -3. [**Your styles.**](#your-styles) All of the CSS you will write for your project. +1. [**Your settings.**](#your-settings) All of your project-specific settings + in the form of Sass variables. +2. [**Scally framework.**](#scally-framework) The entire Scally framework + including your overrides. +3. [**Your styles.**](#your-styles) All of the CSS you will write for your + project. **N.B.** it's imperative this order is maintained otherwise Scally won't work. ### Your settings -Create a new `.scss` file called `settings.scss` that will live in the root of the folder where you keep all of your CSS, along with your master Sass stylesheet: `style.scss`, and link to this file from `style.scss` like so: +Create a new `.scss` file called `settings.scss` that will live in the root of +the folder where you keep all of your CSS, along with your master Sass +stylesheet: `style.scss`, and link to this file from `style.scss` like so: ``` @import "settings"; @@ -190,9 +244,11 @@ Create a new `.scss` file called `settings.scss` that will live in the root of t **This must come before the other two sections.** -In this file you will store all of your common project-specific settings, beyond what Scally offers. Typically you won't have many of these. +In this file you will store all of your common project-specific settings, +beyond what Scally offers. Typically you won't have many of these. -Common project-specific settings might be adding more colours, so if you decide you need a new colour then in `settings.scss` you can create one like so: +Common project-specific settings might be adding more colours, so if you decide +you need a new colour then in `settings.scss` you can create one like so: ``` $color-tertiary: #ccc; @@ -204,41 +260,331 @@ Another example might be adding a new font family e.g. $font-family-droid-sans: "Droid Sans", serif; ``` -The reason this section comes first is so that you can refer to them throughout the rest of your styles. +The reason this section comes first is so that you can refer to them throughout +the rest of your styles. ### Scally framework -This section pulls in the entire Scally framework and is where you override Scally's settings. +This section pulls in the entire Scally framework via Sass [`@import`'s](http://sass-lang.com/guide#topic-5) +and is where you override Scally's settings. -This is what makes Scally so powerful, as Scally can be completely modified by changing the settings without ever having to alter the framework itself. +This is what makes Scally so powerful as Scally can be completely modified by +changing the settings without ever having to alter the framework itself. -So for example if you wanted to change the global font size for your project then you assign a new value to the relevant Scally setting which in this case would be `$font-size` then simply declare it **above** the relevant `@import` partial in `style.scss`, like so: +So for example if you wanted to change the global font size for your project +then you assign a new value to the relevant Scally setting which in this case +would be `$font-size` then simply declare it **above** the relevant `@import` +partial in `style.scss`, like so: ``` $font-size: 14; -@import "bower_components/scally/core/settings/typography"; +@import "[path/to/the/scally]framework]/scally/core/settings/typography"; ``` -You can use your own project-specific settings from your [`settings.scss`](#your-settings) file to override any of the Scally settings e.g. +You can use your own project-specific settings from your +[`settings.scss`](#your-settings) file to override any of the Scally settings +e.g. ``` $color-text-base: $color-hotpink; -@import "bower_components/scally/core/settings/colours"; +@import "[path/to/the/scally]framework]/scally/core/settings/colours"; ``` -By default everything in the framework is imported. But if you want to be selective and you definitely should, so your CSS is as lean as possible, then only import what you need. +By default everything in the framework is imported. But if you want to be +selective and you definitely should, so your CSS is as lean as possible, then +only import what you need. -So if you decide you only need to use half of Scally's utilities then simply remove the relevant utility partial `@import`s you don't need from `style.scss`. +So if you decide you only need to use half of Scally's utilities then simply +remove the relevant utility partial `@import`s you don't need from `style.scss`. -However the **Core** section is required, please do not remove any of the imports from this section. +However the **Core** section is required, please do not remove any of the +`@import`s for this section. ### Your styles -This section is where you pull in all of your project-specific styles. We recommend following the same architecture as the Scally framework. +This section is where you pull in all of your project-specific styles. We +recommend following the [same architecture](#scally-architecture) as the Scally +framework. + +### Master stylesheet template + +Here is a master stylesheet template you could use for your `style.scss`: + +``` +@charset "UTF-8"; + + +/* ============================================================================ + @MASTER STYLESHEET + ========================================================================= */ + + +/** + * Scally, being an OO framework, works in keeping with the open/closed + * principle. Any custom styles *SHOULD NOT* be added or modified in Scally + * directly. This also allows the framework to be updated seamlessly. + * + * Contents: + * + * Your settings.........your project-specific settings. + * Scally framework......the entire Scally framework including your overrides. + * Your styles...........all your project-specific styles. + * + * N.B. the above order and the order within the Scally framework section must + * always be followed. + */ + + + + +/* Your settings + ========================================================================= */ + +/** + * Your project-specific settings. + * + * N.B. define first so they can be used throughout your styles. + */ + +@import "settings"; + + + + +/* Scally framework + ========================================================================= */ + +/** + * By default everything is imported. But if you want to be selective and you + * definitely should, so your CSS is as lean as possible, then only import what + * you want. The Core section is however mandatory. + * + * Any settings you find set in Scally that you do not wish to keep, simply + * redefine above/below the relevant `@import`. This means that if Scally, for + * example, sets your `$font-size` at `16px` and you wish it to be `14px`, + * simply redeclare it above the relevant `@import`, like so: + * + $font-size: 14; + @import "[path/to/the/scally]framework]/core/settings/typography"; + * + * If you want to use a Scally setting to override something then you need to + * define the override below the `@import`, like so: + * + @import "[path/to/the/scally]framework]/core/settings/colours"; + $color-text-base: $color-brand; + * + * If you try to redeclare above the `@import` your Sass won't compile as you + * don't have access to the Scally setting at the point of compilation. + * + * All non-Core settings need to be overridden above the `@import`, like so: + * + $o-arrow-size-base: 14; + $o-arrow-color: orange; + @import "[path/to/the/scally]framework]/objects/o-arrow"; + * + * Scally ignores its own settings in favour of using your own, so you can + * completely modify how Scally works without ever having to alter the + * framework itself. + * + * N.B. the order specified below must always be followed or Scally will + * break. + * + * Contents: + * + * CORE + * LAYOUT + * OBJECTS + * COMPONENTS + * UTILITIES + */ + + +/** + * CORE. + * + * N.B. this is all mandatory for the Scally framework. + */ + +// Settings +@import "[path/to/the/scally]framework]/core/settings/typography"; + +@import "[path/to/the/scally]framework]/core/settings/spacing"; + +@import "[path/to/the/scally]framework]/core/settings/breakpoints"; + +@import "[path/to/the/scally]framework]/core/settings/widths"; + +@import "[path/to/the/scally]framework]/core/settings/colours"; + +@import "[path/to/the/scally]framework]/core/settings/positioning"; + +@import "[path/to/the/scally]framework]/core/settings/cosmetics"; + +// Functions +@import "[path/to/the/scally]framework]/core/functions/convert-px-to-em-rem"; + +@import "[path/to/the/scally]framework]/core/functions/math-helpers"; + +@import "[path/to/the/scally]framework]/core/functions/string-replace"; + +// Mixins +@import "[path/to/the/scally]framework]/core/mixins/convert-px-to-em-rem"; + +@import "[path/to/the/scally]framework]/core/mixins/font-size"; + +@import "[path/to/the/scally]framework]/core/mixins/gradients"; + +@import "[path/to/the/scally]framework]/core/mixins/media-queries"; + +@import "[path/to/the/scally]framework]/core/mixins/generate-at-breakpoints"; + +@import "[path/to/the/scally]framework]/core/mixins/generate-percentage-classes-at-breakpoints"; + +@import "[path/to/the/scally]framework]/core/mixins/retina-bg-image"; + +@import "[path/to/the/scally]framework]/core/mixins/target-browsers"; + +@import "[path/to/the/scally]framework]/core/mixins/target-headings"; + +// Normalize +@import "[path/to/the/scally]framework]/core/normalize"; + +// Reset +@import "[path/to/the/scally]framework]/core/reset"; + +// Base +@import "[path/to/the/scally]framework]/core/base/root"; + +@import "[path/to/the/scally]framework]/core/base/abbreviation"; + +@import "[path/to/the/scally]framework]/core/base/forms"; + +@import "[path/to/the/scally]framework]/core/base/details"; + +@import "[path/to/the/scally]framework]/core/base/headings"; + +@import "[path/to/the/scally]framework]/core/base/horizontal-rule"; + +@import "[path/to/the/scally]framework]/core/base/links"; + +@import "[path/to/the/scally]framework]/core/base/media"; + +@import "[path/to/the/scally]framework]/core/base/paragraphs"; + +@import "[path/to/the/scally]framework]/core/base/print"; + +@import "[path/to/the/scally]framework]/core/base/viewport"; + +// Placeholders +@import "[path/to/the/scally]framework]/core/placeholders/bottom-spacing"; + + +/** + * LAYOUT. + */ + +// Main container +@import "[path/to/the/scally]framework]/layout/l-container"; + +// Grid +@import "[path/to/the/scally]framework]/layout/l-grid"; + +@import "[path/to/the/scally]framework]/layout/l-grid-pull"; + +@import "[path/to/the/scally]framework]/layout/l-grid-push"; + +// Side-by-side +@import "[path/to/the/scally]framework]/layout/l-side-by-side"; + +@import "[path/to/the/scally]framework]/layout/l-side-by-side-alt"; + +// CSS3 columns +@import "[path/to/the/scally]framework]/layout/l-columns"; + + +/** + * OBJECTS. + */ + +@import "[path/to/the/scally]framework]/objects/o-drop-down"; + +@import "[path/to/the/scally]framework]/objects/o-flexible-embed"; + +@import "[path/to/the/scally]framework]/objects/o-link-complex"; + +@import "[path/to/the/scally]framework]/objects/o-link-disguised"; + +@import "[path/to/the/scally]framework]/objects/o-list"; + +@import "[path/to/the/scally]framework]/objects/o-list-block"; + +@import "[path/to/the/scally]framework]/objects/o-list-inline"; + +@import "[path/to/the/scally]framework]/objects/o-arrow"; + +@import "[path/to/the/scally]framework]/objects/o-overlay"; + +@import "[path/to/the/scally]framework]/objects/o-table"; + +@import "[path/to/the/scally]framework]/objects/o-button"; + + +/** + * COMPONENTS. + */ + +@import "[path/to/the/scally]framework]/components/c-button"; + +@import "[path/to/the/scally]framework]/components/c-button-faux-link"; + + +/** + * UTILITIES. + */ + +@import "[path/to/the/scally]framework]/utilities/u-clear-fix"; + +@import "[path/to/the/scally]framework]/utilities/u-text"; + +@import "[path/to/the/scally]framework]/utilities/u-widths"; + +@import "[path/to/the/scally]framework]/utilities/u-alignments"; + +@import "[path/to/the/scally]framework]/utilities/u-toggle-visibility"; + +@import "[path/to/the/scally]framework]/utilities/u-momentum-scrolling"; + +@import "[path/to/the/scally]framework]/utilities/u-float"; + +@import "[path/to/the/scally]framework]/utilities/u-new-block-formatting-context"; + +@import "[path/to/the/scally]framework]/utilities/u-gpu-accelerated"; + +@import "[path/to/the/scally]framework]/utilities/u-position"; + +@import "[path/to/the/scally]framework]/utilities/u-display"; + +@import "[path/to/the/scally]framework]/utilities/u-spacing"; + +@import "[path/to/the/scally]framework]/utilities/u-overflow"; + +@import "[path/to/the/scally]framework]/utilities/u-hide"; + + + + +/* Your styles + ========================================================================= */ + +Start styling your project :) + +``` ### Example architecture -So you may end up with your project setup like this, assuming that you contain all of your CSS in a folder called `css` and you use Bower as your package manager. +So you may end up with your project setup like this—assuming you have contained +all of your CSS in a folder called `css` and you have used Bower as your +package manager: ``` project root @@ -254,10 +600,13 @@ project root └───partials | ├───components + | + ├─── [...] ``` + # Browser support - Chrome (latest two versions). @@ -271,11 +620,16 @@ project root -# Linting +# Authoring guidelines -To ensure a consistently authored code base and to keep things clean and readable Scally uses the [**scss-lint** tool](https://github.com/causes/scss-lint). +Scally follows these [CSS authoring guidelines](https://github.com/chris-pearce/css-guidelines/). -## Installation and usage +## Linting + +To ensure a consistently authored code base and to keep things clean and +readable Scally uses the [**scss-lint** tool](https://github.com/causes/scss-lint). + +### Installation To install run the following command: @@ -289,53 +643,62 @@ To use `cd` into your project's root and run the command: scss-lint ./ ``` -Which will lint *everything*, to lint at a more granular level [see](https://github.com/causes/scss-lint#usage). +Which will lint *everything*, to lint at a more granular level +[see](https://github.com/causes/scss-lint#usage). -## Linting rules +### Linting rules -Scally's linting rules can be [found here](.scss-lint.yml) and are based off [these CSS authoring guidelines](https://github.com/chris-pearce/css-guidelines/). +Scally's linting rules can be [found here](.scss-lint.yml) and are based off +these [CSS authoring guidelines](https://github.com/chris-pearce/css-guidelines/). # Contributing -Scally gratefully welcomes contributions from the open-source community but there are a number of requirements and principles that need to be adhered for code to eligible for inclusion in the framework. +Scally gratefully welcomes contributions from the open-source community. ## Keep it simple -Scally is written in Sass, which provides a lot of incredibly powerful features. However, Scally does not want to become a platform for Sass' capabilities—all code that comes into Scally should be as simple and CSS-like as possible. - -Adding this complexity is against a number of Scally's core principles especially in team-based workflows, long-running and larger projects, and its flexibility. - -Kinds of code not good for Scally: - -- **Hundred-line mixins designed to avoid a couple of lines of repetition:** the overhead of typing a few more lines is much less than creating, documenting, learning, and maintaining complex Sass functionality. -- **Mixins which generate entire blocks of CSS:** creating 'black boxes' in code often leads to obscurity, lack of understanding, lack of confidence, and lack of trust in a codebase. Everything should be as transparent and CSS-like as possible. +Scally is written in Sass, which provides a lot of incredibly powerful features. +However, Scally does not want to become a platform for Sass' capabilities—all +code that comes into Scally should be as simple and CSS-like as possible. ## Submitting code to Scally -In addition to the principles outlined above here are some things to keep in mind when submitting code to Scally via a PR (Pull Request): - -- Lint your Sass, [see](#linting). Scally's build tests will catch any linting issues however it's good practice to run linting manually also. -- Follow [these CSS authoring guidelines](https://github.com/chris-pearce/css-guidelines/). Linting will catch a lot of this but not everything. -- Test in all supported browsers and mobile platforms, [see](#browser-support). - -**Credit:** alot of this section was taken from and inspired by the [Contributing section](https://github.com/inuitcss/CONTRIBUTING/blob/master/README.md) of [inuit.css](https://github.com/csswizardry/inuit.css). +Before submitting code to Scally check the [Scally GitHub issues](https://github.com/chris-pearce/scally/issues) +to see if what you want to add to Scally already exists. If it doesn't then +create a new issue and label appropriately. It's a good idea to wait a few days +for some feedback from the Scally community before writing any code. +To submit code to Scally fork the Scally repository, do your changes, then +create a [GitHub Pull Request](https://help.github.com/articles/using-pull-requests/) +back to the Scally master branch. +Make sure your code is: +- Throughly tested e.g. + - Your Sass compiles both with the Ruby compiler and the LibSass compiler. + - Tested in all supported browsers, [see](#browser-support). +- Linted, lint your Sass, [see](#linting). Scally's build tests will catch any + linting issues however it's good practice to run linting manually also. +- Following these [CSS authoring guidelines](https://github.com/chris-pearce/css-guidelines/). + Linting will catch a lot of this but not everything. -# Scally improvements, issues, and questions +## Scally GitHub issues -If you would like to suggest any new additions to Scally, any improvements, log any issues or bugs, or just ask a question, please [open a new issue](https://github.com/chris-pearce/scally/issues) and label appropriately. +If you would like to suggest any new additions to Scally, any improvements, log +any issues or bugs, or just ask a question, please [open a new GitHub issue](https://github.com/chris-pearce/scally/issues) +and label appropriately. # Versioning -Scally is maintained under the [Semantic Versioning guidelines](http://semver.org/) however sometimes we get it wrong, but we will do our best to adhere to those rules as much as possible and strive to maintain backwards compatibility. +Scally is maintained under the [Semantic Versioning guidelines](http://semver.org/) +however sometimes we get it wrong, but we will do our best to adhere to thoee +rules as much as possible and strive to maintain backwards compatibility. [See the **CHANGELOG**](CHANGELOG.md). @@ -360,21 +723,27 @@ Copyright 2015 Chris Pearce. [View license](LICENSE). -Licensed under the [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0) license. +Licensed under the [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0) +license. -Scally was originally created at [Westfield Labs](http://www.westfieldlabs.com/) whilst I was an employee there. +Scally was originally created at [Westfield Labs](http://www.westfieldlabs.com/) +whilst I was an employee there. -Scally was something I brought to Westfield Labs, and something I worked on full-time for a period of time as the main developer. Other Westfield Labs employees who contributed to Scally at that time: +Scally was something I brought to Westfield Labs, and something I worked on +full-time for a period of time as the main developer. Other Westfield Labs +employees who contributed to Scally at that time: - [Alec Raeside](http://alecraeside.com.au/) - [Kate Levin](http://kllevin.com/) - [Dan Sim](http://daniel-sim.com/) -After I finished at Westfield Labs I decided to fork Scally so I could maintain it myself under my own personal GitHub account. +After I finished at Westfield Labs I decided to fork Scally so I could maintain +the framework myself under my own personal GitHub account. -# Presentations +# Further documentation -- (done for my current employer [Campaign Monitor](https://www.campaignmonitor.com/) in Jan 2015) +- [A presentation on Scally on Jan 2015](http://scally.chris-pearce.me/presentation) + —for my current employer [Campaign Monitor](https://www.campaignmonitor.com/).