Skip to content
Snippets Groups Projects
  • Matt Wang's avatar
    c2ec3d89
    Update Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues (#821) · c2ec3d89
    Matt Wang authored
    This is a catch-all PR that modernizes and updates our Stylelint config, and resolves all open issues. This is a pretty big change - so I want to update all of our related dependencies in lockstep.
    
    In particular, this PR
    
    - [x] updates stylelint to `v14`
    - [x] adds in the standard stylelint config for SCSS (`stylelint-config-standard-scss`)
    - [x] swaps out `stylelint-config-prettier` for `stylelint-config-prettier-scss`
    - [x] ~~properly update `@primer`-related plugins:~~ completely remove `primer` from our configuration
    - [x] autofix, manually resolve, or disable all newly-introduced lint errors; **I've avoided manually resolving errors that would be a behavioural change**
    - [x] re-runs `npm run format`
    
    See the "next steps" section on some extra thoughts on disabling errors.
    
    (implicitly, I'm also using node 16/the new package-lock format).
    
    ### disabling rules and next steps
    
    I've introduced several new disabled rules. Let me quickly explain what's going on; there are two categories of rules I've disabled:
    
    1. rules that were temporary disables; they were frequent enough that I couldn't manually resolve them, but should be simple. **I plan on opening issues to re-enable each of these rules**, just after this PR
        - `declaration-block-no-redundant-longhand-properties`: this is just tedious and error-prone
        - `no-descending-specificity`: this one is tricky since it could have impacts on the cascade (though that seems unlikely)
        - `scss/no-global-function-names`: I think we need to [import map and then use `map.get`](https://stackoverflow.com/questions/64210390/sass-map-get-doesnt-work-map-get-does-what-gives), but I'll leave this as out of scope for now
    2. rules that are long-term disables; due to the SASS-based nature of our theme, I think we'll keep these in limbo
        - `alpha-value-notation` causes problems with SASS using the `modern` syntax - literals like `50%` are not properly interpolated, and they cause formatting issues on the site
        - `color-function-notation` also causes problems with SASS, but in this case the `modern` syntax breaks SASS compilation; we're not alone (see this [SO post](https://stackoverflow.com/questions/71805735/error-function-rgb-is-missing-argument-green-in-sass)). 
    
    In addition, we have many inline `stylelint-disable` comments. I'd open a separate issue to audit them, especially since I think some disables are unnecessary.
    
    ### on Primer 
    
    **note: there hasn't been much other discussion, so I'm going to remove primer's stylelint config.**
    
    If I do add `@primer/stylelint-config`, I get *a ton* of errors about now using `@primer`'s in-built SCSS variables. I imagine that we probably won't want to use these presets (though I could be wrong). In that case, I think we could either:
    
    1. disable all of those rules
    4. not use `@primer/stylelint-config`, since we're not actually using primer, and shift back to the standard SCSS config provided by Stylelint
    
    ~~Any thoughts here? I also don't have the original context as to why we do use the primer rules, perhaps @pmarsceill can chime in?~~
    Update Stylelint to v14, extend SCSS plugins, remove primer-* configs, resolve issues (#821)
    Matt Wang authored
    This is a catch-all PR that modernizes and updates our Stylelint config, and resolves all open issues. This is a pretty big change - so I want to update all of our related dependencies in lockstep.
    
    In particular, this PR
    
    - [x] updates stylelint to `v14`
    - [x] adds in the standard stylelint config for SCSS (`stylelint-config-standard-scss`)
    - [x] swaps out `stylelint-config-prettier` for `stylelint-config-prettier-scss`
    - [x] ~~properly update `@primer`-related plugins:~~ completely remove `primer` from our configuration
    - [x] autofix, manually resolve, or disable all newly-introduced lint errors; **I've avoided manually resolving errors that would be a behavioural change**
    - [x] re-runs `npm run format`
    
    See the "next steps" section on some extra thoughts on disabling errors.
    
    (implicitly, I'm also using node 16/the new package-lock format).
    
    ### disabling rules and next steps
    
    I've introduced several new disabled rules. Let me quickly explain what's going on; there are two categories of rules I've disabled:
    
    1. rules that were temporary disables; they were frequent enough that I couldn't manually resolve them, but should be simple. **I plan on opening issues to re-enable each of these rules**, just after this PR
        - `declaration-block-no-redundant-longhand-properties`: this is just tedious and error-prone
        - `no-descending-specificity`: this one is tricky since it could have impacts on the cascade (though that seems unlikely)
        - `scss/no-global-function-names`: I think we need to [import map and then use `map.get`](https://stackoverflow.com/questions/64210390/sass-map-get-doesnt-work-map-get-does-what-gives), but I'll leave this as out of scope for now
    2. rules that are long-term disables; due to the SASS-based nature of our theme, I think we'll keep these in limbo
        - `alpha-value-notation` causes problems with SASS using the `modern` syntax - literals like `50%` are not properly interpolated, and they cause formatting issues on the site
        - `color-function-notation` also causes problems with SASS, but in this case the `modern` syntax breaks SASS compilation; we're not alone (see this [SO post](https://stackoverflow.com/questions/71805735/error-function-rgb-is-missing-argument-green-in-sass)). 
    
    In addition, we have many inline `stylelint-disable` comments. I'd open a separate issue to audit them, especially since I think some disables are unnecessary.
    
    ### on Primer 
    
    **note: there hasn't been much other discussion, so I'm going to remove primer's stylelint config.**
    
    If I do add `@primer/stylelint-config`, I get *a ton* of errors about now using `@primer`'s in-built SCSS variables. I imagine that we probably won't want to use these presets (though I could be wrong). In that case, I think we could either:
    
    1. disable all of those rules
    4. not use `@primer/stylelint-config`, since we're not actually using primer, and shift back to the standard SCSS config provided by Stylelint
    
    ~~Any thoughts here? I also don't have the original context as to why we do use the primer rules, perhaps @pmarsceill can chime in?~~
devcontainer.json 1.18 KiB
// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll
{
  "name": "Just the docs",
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      // Update 'VARIANT' to pick a Debian OS version: bullseye, buster
      // Use bullseye when on local arm64/Apple Silicon.
      "VARIANT": "bullseye",
      // Enable Node.js: pick the latest LTS version
      "NODE_VERSION": "lts/*"
    }
  },

  // Set *default* container specific settings.json values on container create.
  "settings": {},

  // Add the IDs of extensions you want installed when the container is created.
  "extensions": ["GitHub.vscode-pull-request-github"],

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  "forwardPorts": [
    // Jekyll server
    4000,
    // Live reload server
    35729
  ],

  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "sh .devcontainer/post-create.sh",

  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
  "remoteUser": "vscode"
}