Stylelint is a mighty, modern linter that helps you avoid errors and enforce conventions in your styles.

Using Zasaf as our in-house approach to write modular CSS with easily maintainable and scalable stylesheets, we have a very opinionated picture of what our CSS should look like. Therefore, we decided to use a Zweitag-wide configuration and deviate from the standard rules. The configuration provided in this repository helps on the one hand to write better CSS and on the other hand to fulfil parts of the goals and guidelines of Zasaf.

The stylelint documentation is very good and explains each rule (and a lot more) in detail.

The commonly usable config file is located here in this repository.

It is based on some simple principles:

1. Exceptions should be justified and documented (in a comment). You don't want to ask yourself in a month if it wouldn't be better to remove the exception and so on.
2. Exceptions should be as small as possible, meaning that if for example you have to turn off a rule because it makes sense for files in stylesheets/globals for example, just disable it for this directory, not globally!

For versions 1.x.x of this package, see here

Projects which are generated from our rails template repository should automatically use this config. The Zweitag stylelint configuration is available as a package in the private github package registry of the zweitag organization.

In order to get access to the registry you need to specify the registry for the @zweitag scope. This can be done by adding to following things to .npmrc:

@zweitag:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=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

Note: .npmrc needs to be in the same folder as package.json!

Afterwards you can use and install the package like you normally would:

yarn add --dev @zweitag/stylelint-config
or
npm install --save-dev @zweitag/stylelint-config

Additionally you need a .stylelintrc.json where you extend our global configuration:

{
  "extends": "@zweitag/stylelint-config"
}

Since version 14 no other syntaxes than CSS are directly supported by Stylelint. Instead, the corresponding syntaxes must be added as a package. You can find more details here. In this case the config file should be included like this:

{
  "extends": [
    "stylelint-config-html/vue", // replace or add other syntaxes
    "@zweitag/stylelint-config"
  ],
}

If you lint more than one styling language, then you can use the new overrides property.

Situations will arise where you have to deactivate stylelint rules for certain cases. This can be done with the help of the comment ignore syntax, but ensure to disable only the specific rules:

// stylelint-disable-next-line [rules] -- comment

or

// stylelint-disable-line [rules] -- comment

or

// stylelint-disable [rules] -- comment
.block {
  width: 100px;
}
// stylelint-enable [rules]

There is a more detailed documentation of this feature available in the stylelint docs.

In some cases, some rules must also be overridden or deactivated project-wide. To do this, you can simply override a rule in your .stylelintrc.json. If it makes sense to adapt the rule for all projects, you are welcome to create a pull request for the central configuration in this repository.

If you just want to ignore some specific files, you can create a .stylelintignore including the github glob-pattern for the files to be ignored. The node_modules-folder is ignored by default.

As you are migrating an existing project, there is a --fix option, auto-correcting simple errors and code smells. In case you don't want to migrate the whole project at once, you can use the comment ignore syntax or the .stylelintignore to handle larger code smells when there is time and budget.

If you feel that a rule that is currently enabled/disabled should be changed in the shared config, for example because ...

• it doesn't make sense in our circumstances (like enforcing documentation which we usually don't)
• or it does make absolutely no sense whatsoever
• ...

please feel free to discuss the rule

• in the office
• during hack teams
• on slack
• in a github issue or a github pull request
• ...

and eventually create a pull request that does the following:

• enables/disables the rule(s) or adds exceptions regarding files in the config file
• adds a comment directly beside or beneath the exception explaining why it exists
• probably links some more resources or reasons for the decision (e.g. a slack conversation) on the pull request (not in the config)

We use tags for releases, so to release a new version do the following:

1. Increase the version in /stylelint/package.json
2. Document changes in stylelint/CHANGELOG.md
3. Create a PR, if not existing already
4. Merge PR (after Review / CI) to main
5. Checkout main on your machine and bring it up-to-date with git pull
6. Tag commit on main with the new version: git tag x.x.x
7. Push tag to Github: git push origin x.x.x

Make sure that the version numbers match with the changes.

• [breaking]: Major version bump.
• [update]: Minor version bump.
• [new]: Minor version bump.
• [fix]: patch version bump.

Last but not least, feel free to also discuss and adjust this readme.