Task: Set up codestyle guidelines and automated tooling #190

New issue

Open

opened 2024-11-11 20:14:56 +00:00 by 2nPlusOne · 0 comments

2nPlusOne commented

2024-11-11 20:14:56 +00:00

(Migrated from github.com)

Set up codestyle guidelines and automated tooling

As a developer, I want my environment to automatically style my code according to the project conventions, so that I can easily maintain project-wide consistency in code style.

Additional notes/thoughts

As for the specific prettier configuration that should be used... the defaults should be fine for the most part. If in doubt, look for an example in the repo. Otherwise, look for best practices in popular projects in the same tech ecosystem.

Prettier is a gold standard for this sort of thing. A unified prettier config should be enforced for all developers working on the project. Additionally, it is common practice to setup a git hook that runs the prettier checks to make sure that the repo is consistently maintaining the code style. It's fairly common for developers to set their IDE to autoformat using the prettier config on save, so there isn't an avalanche of violations when the git hook runs. I think this can be enforced in the workspace settings (which can be manually overridden by developers if they have personal preferences).

simple-git-hooks is a package that does as the name suggests: drastically reduces the amount of configuration required to get a basic git hook setup for pre-commit, etc.

Getting the prettier config setup to also format Tailwind class strings can be a bit tricky as there is conflicting info on the web last time I checked, but is definitely worth it for the added layer of consistency in the sorted classnames. Combine that with separating groups of classes onto separate lines in separate strings and it's just 🤌. Making a cn function using clsx and tailwindMerge is a good way to do that cleanly (see shadcn docs for an example).

// next/lib/classname.ts        (or added to utils.ts)
import clsx from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...classes: string[]) {
  return twMerge(clsx(...classes));
}

Definition of Done

Acceptance criteria defined
Solution tasks specified
Feature branch created (called 190-setup-prettier-tooling or similar)
Design documents updated if needed
Pull request created
Code is reviewed
Code is merged to develop branch
~~Tests pass on CI~~
~~Deployed to staging environment~~
Acceptance criteria is met

Acceptance Criteria

Given I have cloned the repo, when I open it in VSCode, then I should get a prompt to install the recommended plugins including necessary plugins for prettier.
Given I haven't overridden the autoformat on save setting in my user settings, when I save a code file, then the file should automatically format using the prettier config in the prettier config file.
Given I have changes staged, when I commit those changes, then the pre-commit hook should run a suite of commands to validate the repo's files against the prettier config.
Given I have installed the required VSCode extensions, when I open a code file, then the extensions should provide relevant linting and formatting suggestions according to the Prettier configuration.
Given I have made changes to Tailwind CSS classes, when I save the file, then the Tailwind CSS classes should be automatically sorted and formatted.
Given I have committed my changes, when I push the commit, then the CI pipeline should run Prettier checks and fail if there are any formatting issues.

Solution Tasks

Set up a Prettier configuration file with the desired settings.
- Create a .prettierrc file in the root directory.
- Define the desired code style settings (e.g., tab width, single quotes, trailing commas).
Configure VSCode workspace settings to recommend necessary plugins, including Prettier.
- Add a .vscode folder with extensions.json to recommend Prettier and other necessary extensions.
- Add a settings.json file in the .vscode folder to enforce Prettier formatting on save.
Install and configure simple-git-hooks to set up pre-commit hooks for running Prettier checks.
- Add simple-git-hooks to the project dependencies.
- Create a pre-commit hook script to run Prettier checks on staged files.
- Configure the package.json to use simple-git-hooks.
Ensure that Tailwind class strings are formatted correctly by configuring Prettier with the necessary plugins and settings.
- Install prettier-plugin-tailwindcss and add it to the Prettier configuration.
- Test the configuration to ensure Tailwind classes are sorted correctly.
Implement a cn function using clsx and tailwindMerge for managing Tailwind classnames cleanly.
- Add clsx and tailwind-merge to the project dependencies.
- Create a utility function cn that combines and merges classnames using clsx and tailwind-merge.
Update environment setup documentation to include instructions for setting up the Prettier configuration and git hooks.
- Add detailed setup instructions to the EnvironmentSetup.md file.
- Include steps for installing necessary dependencies and running setup scripts.
Ensure all team members are aware of the new guidelines and tooling by conducting a knowledge-sharing session.
- Schedule a meeting or workshop to present the new guidelines and tooling.
- Prepare a presentation or documentation to explain the changes and how to use the new tools.
- Gather feedback and address any questions or concerns from the team.

References

NOTE: The version of Copilot integrated with GitHub.com assisted with fleshing out the enumeration aspects of this ticket. So if anything looks off, just drop a comment.

# Set up codestyle guidelines and automated tooling As a **developer**, I want **my environment to automatically style my code according to the project conventions**, so that **I can easily maintain project-wide consistency in code style.** ## Additional notes/thoughts As for the specific prettier configuration that should be used... the defaults should be fine for the most part. If in doubt, look for an example in the repo. Otherwise, look for best practices in popular projects in the same tech ecosystem. Prettier is a gold standard for this sort of thing. A unified prettier config should be enforced for all developers working on the project. Additionally, it is common practice to setup a git hook that runs the prettier checks to make sure that the repo is consistently maintaining the code style. It's fairly common for developers to set their IDE to autoformat using the prettier config on save, so there isn't an avalanche of violations when the git hook runs. I think this can be enforced in the workspace settings (which can be manually overridden by developers if they have personal preferences). `simple-git-hooks` is a package that does as the name suggests: drastically reduces the amount of configuration required to get a basic git hook setup for pre-commit, etc. Getting the prettier config setup to also format Tailwind class strings can be a bit tricky as there is conflicting info on the web last time I checked, but is definitely worth it for the added layer of consistency in the sorted classnames. Combine that with separating groups of classes onto separate lines in separate strings and it's just 🤌. Making a `cn` function using clsx and tailwindMerge is a good way to do that cleanly (see shadcn docs for an example). ```ts // next/lib/classname.ts (or added to utils.ts) import clsx from 'clsx'; import { twMerge } from 'tailwind-merge'; export function cn(...classes: string[]) { return twMerge(clsx(...classes)); } ``` ## Definition of Done - [x] Acceptance criteria defined - [x] Solution tasks specified - [x] Feature branch created (called `190-setup-prettier-tooling` or similar) - [x] Design documents updated if needed - [x] Pull request created - [ ] Code is reviewed - [ ] Code is merged to `develop` branch - [ ] ~~Tests pass on CI~~ - [ ] ~~Deployed to staging environment~~ - [ ] Acceptance criteria is met ## Acceptance Criteria - [ ] Given **I have cloned the repo**, when **I open it in VSCode**, then **I should get a prompt to install the recommended plugins including necessary plugins for prettier.** - [ ] Given **I haven't overridden the autoformat on save setting in my user settings**, when **I save a code file**, then **the file should automatically format using the prettier config in the prettier config file.** - [ ] Given **I have changes staged**, when **I commit those changes**, then **the pre-commit hook should run a suite of commands to validate the repo's files against the prettier config.** - [ ] Given **I have installed the required VSCode extensions**, when **I open a code file**, then **the extensions should provide relevant linting and formatting suggestions according to the Prettier configuration**. - [ ] Given **I have made changes to Tailwind CSS classes**, when **I save the file**, then **the Tailwind CSS classes should be automatically sorted and formatted**. - [ ] Given **I have committed my changes**, when **I push the commit**, then **the CI pipeline should run Prettier checks and fail if there are any formatting issues**. ## Solution Tasks - [x] Set up a Prettier configuration file with the desired settings. - [x] Create a `.prettierrc` file in the root directory. - [x] Define the desired code style settings (e.g., tab width, single quotes, trailing commas). - [x] Configure VSCode workspace settings to recommend necessary plugins, including Prettier. - [x] Add a `.vscode` folder with `extensions.json` to recommend Prettier and other necessary extensions. - [x] Add a `settings.json` file in the `.vscode` folder to enforce Prettier formatting on save. - [ ] Install and configure `simple-git-hooks` to set up pre-commit hooks for running Prettier checks. - [ ] Add `simple-git-hooks` to the project dependencies. - [ ] Create a `pre-commit` hook script to run Prettier checks on staged files. - [ ] Configure the `package.json` to use `simple-git-hooks`. - [x] Ensure that Tailwind class strings are formatted correctly by configuring Prettier with the necessary plugins and settings. - [x] Install `prettier-plugin-tailwindcss` and add it to the Prettier configuration. - [x] Test the configuration to ensure Tailwind classes are sorted correctly. - [ ] Implement a `cn` function using `clsx` and `tailwindMerge` for managing Tailwind classnames cleanly. - [ ] Add `clsx` and `tailwind-merge` to the project dependencies. - [ ] Create a utility function `cn` that combines and merges classnames using `clsx` and `tailwind-merge`. - [ ] Update environment setup documentation to include instructions for setting up the Prettier configuration and git hooks. - [ ] Add detailed setup instructions to the `EnvironmentSetup.md` file. - [ ] Include steps for installing necessary dependencies and running setup scripts. - [ ] Ensure all team members are aware of the new guidelines and tooling by conducting a knowledge-sharing session. - [ ] Schedule a meeting or workshop to present the new guidelines and tooling. - [ ] Prepare a presentation or documentation to explain the changes and how to use the new tools. - [ ] Gather feedback and address any questions or concerns from the team. ## References - [Environment Setup Guide](documentation/EnvironmentSetup.md) - [Next.js README](next/README.md) # NOTE: The version of Copilot integrated with GitHub.com assisted with fleshing out the enumeration aspects of this ticket. So if anything looks off, just drop a comment.