diff --git a/.gitignore b/.gitignore index c8ceb27434..d98495eec9 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ /docs/_build/ /.tox/ /venv +/node_modules/ diff --git a/.scss-lint.yml b/.scss-lint.yml new file mode 100644 index 0000000000..5589b866c9 --- /dev/null +++ b/.scss-lint.yml @@ -0,0 +1,154 @@ + +scss_files: 'wagtail/*/static/**/*.scss' +exclude: 'wagtail/**/static/**/vendor/*.scss' + +linters: + BorderZero: + enabled: true + + Indentation: + severity: warning + width: 4 + allow_non_nested_indentation: true + character: space + + ColorKeyword: + enabled: true + + ColorVariable: + enabled: true + + BangFormat: + space_before_bang: true + space_after_bang: false + + Comment: + enabled: true + + DeclarationOrder: + enabled: true + + DuplicateProperty: + enabled: false + + ElsePlacement: + enabled: true + + EmptyLineBetweenBlocks: + enabled: true + + EmptyRule: + enabled: true + + FinalNewline: + present: true + + HexLength: + style: short + + HexNotation: + style: lowercase + + HexValidation: + enabled: true + + IdSelector: + enabled: true + + ImportantRule: + enabled: true + + ImportPath: + enabled: true + + LeadingZero: + style: exclude_zero + + MergeableSelector: + enabled: false + + NameFormat: + allow_leading_underscore: true + + NestingDepth: + max_depth: 4 + + SelectorDepth: + max_depth: 3 + + SelectorFormat: + convention: hyphenated_lowercase + ignored_names: + - js_class + ignored_types: + - element + + PlaceholderInExtend: + enabled: true + + PropertyCount: + enabled: false + + QualifyingElement: + allow_element_with_attribute: false + allow_element_with_class: false + allow_element_with_id: false + + Shorthand: + enabled: true + + SingleLinePerProperty: + enabled: true + allow_single_line_rule_sets: true + + SingleLinePerSelector: + enabled: true + + SpaceAfterComma: + enabled: true + + SpaceAfterPropertyColon: + style: at_least_one_space + + SpaceAfterPropertyName: + enabled: true + + SpaceBeforeBrace: + enabled: true + allow_single_line_padding: true + style: space + + SpaceBetweenParens: + enabled: true + + StringQuotes: + style: single_quotes + + TrailingSemicolon: + enabled: true + + TrailingZero: + enabled: true + + UnnecessaryMantissa: + enabled: true + + UnnecessaryParentReference: + enbabled: true + + UrlFormat: + enabled: true + + UrlQuotes: + enabled: true + + VariableForProperty: + enabled: false + + VendorPrefix: + enabled: false + + ZeroUnit: + enabled: true + + diff --git a/docs/contributing/css_guidelines.rst b/docs/contributing/css_guidelines.rst new file mode 100644 index 0000000000..26d1e5e123 --- /dev/null +++ b/docs/contributing/css_guidelines.rst @@ -0,0 +1,168 @@ +CSS coding guidelines +=========================== + +Our CSS is written in Sass, using the SCSS syntax. + +Spacing +~~~~~~~ + +- Use soft-tabs with a four space indent. Spaces are the only way to + guarantee code renders the same in any person's environment. +- Put spaces after ``:`` in property declarations. +- Put spaces before ``{`` in rule declarations. +- Put line breaks between rulesets. +- When grouping selectors, keep individual selectors to a single line. +- Place closing braces of declaration blocks on a new line. +- Each declaration should appear on its own line for more accurate + error reporting. +- Add a newline at the end of your ``.scss`` files. +- Strip trailing whitespace from your rules. + +Formatting +~~~~~~~~~~ + +- Use hex color codes ``#000`` unless using ``rgba()`` in raw CSS + (SCSS' ``rgba()`` function is overloaded to accept hex colors as a + param, e.g., ``rgba(#000, .5)``). +- Use ``//`` for comment blocks (instead of ``/* */``). +- Use single quotes for string values + ``background: url('my/image.png')`` or ``content: 'moose'`` +- Avoid specifying units for zero values, e.g., ``margin: 0;`` instead + of ``margin: 0px;``. +- Strive to limit use of shorthand declarations to instances where you + must explicitly set all the available values. + +Sass imports +~~~~~~~~~~~~ + +Leave off underscores and file extensions in includes: + +.. code-block:: scss + + // Bad + @import 'components/_widget.scss' + + // Better + @import 'components/widget' + +Pixels vs. ems +~~~~~~~~~~~~~~ + +Use ``rems`` for ``font-size``, because they offer +absolute control over text. Additionally, unit-less ``line-height`` is +preferred because it does not inherit a percentage value of its parent +element, but instead is based on a multiplier of the ``font-size``. + +Specificity (classes vs. ids) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Always use classes instead of IDs in CSS code. IDs are overly specific and lead +to duplication of CSS. + +When styling a component, start with an element + class namespace, +prefer direct descendant selectors by default, and use as little +specificity as possible. Here is a good example: + +.. code-block:: html + + + +.. code-block:: scss + + .category-list { // element + class namespace + + // Direct descendant selector > for list items + > li { + list-style-type: disc; + } + + // Minimal specificity for all links + a { + color: #f00; + } + } + +Class naming conventions +~~~~~~~~~~~~~~~~~~~~~~~~ + +Never reference ``js-`` prefixed class names from CSS files. ``js-`` are +used exclusively from JS files. + +Use the SMACSS ``is-`` `prefix `__ +for state rules that are shared between CSS and JS. + +Misc +~~~~ + +As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for +three levels. If you cannot help it, step back and rethink your overall +strategy (either the specificity needed, or the layout of the nesting). + +Examples +~~~~~~~~ + +Here are some good examples that apply the above guidelines: + +.. code-block:: scss + + // Example of good basic formatting practices + .styleguide-format { + color: #000; + background-color: rgba(0, 0, 0, .5); + border: 1px solid #0f0; + } + + // Example of individual selectors getting their own lines (for error reporting) + .multiple, + .classes, + .get-new-lines { + display: block; + } + + // Avoid unnecessary shorthand declarations + .not-so-good { + margin: 0 0 20px; + } + .good { + margin-bottom: 20px; + } + +Vendor prefixes +~~~~~~~~~~~~~~~ + +Line up your vendor prefixes. + +.. code-block:: scss + + // Example of good prefix formatting practices + .styleguide-format { + -webkit-transition: opacity 0.2s ease-out; + -moz-transition: opacity 0.2s ease-out; + -ms-transition: opacity 0.2s ease-out; + -o-transition: opacity 0.2s ease-out; + transition: opacity 0.2s ease-out; + } + +Don't write vendor prefixes for ``border-radius``, it's pretty well supported. + +If you're unsure, you can always check support at +`caniuse `_ + + +Linting SCSS +~~~~~~~~~~~~ + +The guidelines are included in a ``.scss-lint.yml`` file so that you can +check that your code conforms to the style guide. + +Run the linter with ``scss-lint .`` from the wagtail project root. +You'll need to have the linter installed to do this. You can get it by +running: + +.. code-block:: bash + + gem install scss-lint diff --git a/docs/howto/contributing.rst b/docs/contributing/developing.rst similarity index 99% rename from docs/howto/contributing.rst rename to docs/contributing/developing.rst index f43c63d46d..cff5426737 100644 --- a/docs/howto/contributing.rst +++ b/docs/contributing/developing.rst @@ -1,4 +1,4 @@ -Contributing to Wagtail +Developing Wagtail ----------------------- Issues diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 0000000000..e5324a2bf4 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,9 @@ +Contributing to Wagtail +====== + + +.. toctree:: + :maxdepth: 2 + + developing + css_guidelines diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 2271642aa6..4d630f03f2 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -10,5 +10,4 @@ How to performance multilingual_sites custom_branding - contributing third_party_tutorials diff --git a/docs/index.rst b/docs/index.rst index e730e6d8ad..9df312c697 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,4 +43,5 @@ Index reference/index support editor_manual/index + contributing/index releases/index