This repo provides a set of npm packages that configure the awesome tooling we use every day. There are a lot of these standards out there, but as a company we have specific needs, so this is here to serve us in the best way.
Also, when you have too many standards, xkcd recommends to create a new standard (Source).
By having a vision, we can make some decisions more easily by refering back to this vision and how a change contributes to this vision.
The goal of JS Config is to improve the productivity of our developers (in the long term). This means we should strive for (in order of importance):
- Consistency: auto-formatting / auto-sorting stuff: Developers should not need to think about this stuff and still find their code in a readable and consistent order / syntax. There shouldn't be a lot of discussion about which style to pick as it's just a matter of taste and getting used too. Let's try to stay as close as possible to "community standards".
- Correctness: small bugs (e.g. eslint rules about hooks) should be catched by eslint not by (human) reviews. Rules that catch potential bugs and with few false positives should be enabled.
- Code Quality: Rules that help in code quality and are not flagging too many false positives could be enabled as well.
- Unity: Having as many configs as possible in this repo and use it in as many projects as possible with at little adaptation as possible (but adaptation is still allowed!). That way engineers can assume a good and working setup and donβt need to catch little bugs during review time if a linter can do this.
(If you are using npm, you should use npm install
instead of yarn add
)
yarn add -D eslint @datacamp/eslint-config
Create a file .eslintrc.js
with the following contents
// .eslintrc.js
module.exports = {
extends: ['@datacamp/eslint-config'],
};
For typescript projects you can use the following config:
// .eslintrc.js
module.exports = {
extends: ['@datacamp/eslint-config/typescript'],
};
For front-end projects, you might want to adjust the environment:
// .eslintrc.js
module.exports = {
// [...]
env: {
browser: true,
},
};
Afterwards you can run eslint as follows:
yarn eslint . --ext ts,js,json --ignore-path .gitignore
It's recommended to:
- also install our common prettier config (as ESlint config uses your prettier config to lint for code style)
- install an eslint plugin for your editor of choice (to see errors / warnings in your editor)
yarn add -D prettier @datacamp/prettier-config
Create a file prettier.config.js
with the following contents
// prettier.config.js
module.exports = {
...require('@datacamp/prettier-config'),
};
It's recommended to:
- also install eslint to check whether your files are following your prettier config.
- install prettier plugin for your editor of choice
All the configs are in the packages/
directory. We use lerna to manage dependencies.
Install the dependencies for all the subpackages using yarn
in the root of the project.
If you need help, ping the #javascript channel on Slack.
- Try out the configuration in your own project for a while (so the cost / benefit trade-off becomes more apparent)
- Create a PR (or an issue with a proposal if the PR would be a lot of work) outlying the changes + why it's a good idea. You can refer to the vision on what level it improves developer productivity (Consistency, Correctness, Code Quality, Unity).
- Communicate proposal in #javascript channel on Slack
- On the next javascript guild meeting, we go over all open PRs and quickly discuss as a group on whether we think it's a good idea. For this, we base ourselves on the vision. A change that fits the vision well has a higher chance of getting merged.
We use commitlint to lint our commit messages and follow config-conventional. The version of the packages will be bumped based on the commit messages as well, see the conventional commits website for more information (short version: fix=patch, feat=minor, BREAKING CHANGE footer=major)
It's hard to know what is a breaking change so these our the guidelines:
- It's a breaking change if it adds new errors that are not auto-fixable. So after running eslint --fix you should be good again and you just need to review the things it fixed
- It's a breaking change if it expects to change a lot of code on --fix E.g. object literal properties should be ordered (it's auto fixable but it's gonna mess up a lot of code). Most prettier changes will also fall under this
So in short, users should be able to run eslint --fix
(or equivalent) and review a few things but it should be doable to review in <10 minutes, even for large projects.
Other changes could qualify as well but then we basically always have major changes and almost never minor so that's why we choose these guidelines (for now). We're open to change them if they don't work for us.
You can publish all the packages you've edited. This will run lerna publish
under the hood:
yarn release
This will propose version numbers for you and push a commit with a changelog to all the individual packages.
Please only run this from main and make sure to pull the latest main before you run it. Running it will push a commit to main which the updated changelog etc.