From d83935f9daa47c58edb3944275431e8242bbe124 Mon Sep 17 00:00:00 2001 From: alimpens Date: Wed, 17 Jul 2024 14:14:12 +0200 Subject: [PATCH 01/10] chore: Update contributing docs --- CONTRIBUTING.md | 134 +++++++++++++++++++++------- documentation/definition-of-done.md | 1 - 2 files changed, 101 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c12ae7fa87..739492d370 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,66 @@ -# Contributing +# Contributing Guidelines -Before starting work on a new component, check the [NL Design System community](https://github.com/nl-design-system/) for components that might already do exactly what you want. -If these don’t exist, or aren’t up to our requirements, we can add a new component. + -Please also follow these contribution guidelines from the NL Design System community: +## Contents + +- [Code of Conduct](#book-code-of-conduct) + +- [Opening an Issue](#inbox_tray-opening-an-issue) +- [Submitting Pull Requests](#repeat-submitting-pull-requests) +- [Credits](#pray-credits) + + + +## :book: Code of Conduct + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. +Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_OF_CONDUCT.md) if you haven’t already. + + + +## :inbox_tray: Opening an issue + +Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first. + +### :lock: Reporting security issues + +Review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). **Do not** file a public issue for security vulnerabilities. + +### :beetle: Bug reports and other issues + +For all other issues, you can [create an issue on GitHub](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue). + +Follow these guidelines when doing so: + +- **Do not open a duplicate issue.** Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have. You may simply note "I have this problem too", which helps prioritize the most common problems and requests. + +- **Prefer using [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)**, not comments, if you simply want to "+1" an existing issue. + +- **Fully complete the provided issue template.** The bug report template requests all the information we need to quickly and efficiently address your issue. Be clear, concise, and descriptive. + +## :repeat: Submitting pull requests + +Before opening a pull request for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended approach for solving the problem in the comments for an existing issue. + +### Git workflows + +We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) for this project. +Members of the [Amsterdam GitHub organisation](https://github.com/Amsterdam) can request push access to the repository, +to be able to push branches. +If you do not want access, you can [fork the repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) and [submit a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests). +We currently do not have a workflow for contributors that do not work for the City of Amsterdam. +If you do not work for the City of Amsterdam and want to contribute to this repository, please contact the [maintainers](./documentation/maintainers.md). + +### Contribution guidelines + +Please follow these contribution guidelines from the NL Design System community: - [Accessibility](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-accessibility--docs) - [CSS](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-css--docs) @@ -14,16 +69,35 @@ Please also follow these contribution guidelines from the NL Design System commu - [npm package](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-npm-package--docs) - [Storybook](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-storybook--docs) -## Aligning with design/UX +Also follow our [CSS](./packages/css/documentation/coding-conventions.md) and [React](./packages/react/documentation/coding-conventions.md) coding conventions. -Currently, you can find the most up-to-date documentation on design and UX on [amsterdam.nl/designsystem](https://amsterdam.nl/designsystem). -In time, the Storybook(s) in this repository should be the definitive source for documentation on code, design and UX. +### Aligning with design/UX + +You can find the most up-to-date documentation on design and UX in the Storybook in this repository. If you want to add a component, first check if it’s already included in our [Figma Library](). If there is no design, or if you have questions about an existing design, please contact . -## Install prerequisites +### Pull request guidelines + +- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. + +- **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing! + +- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it. + +- **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future. + +- **[Follow our Definition of Done](https://github.com/Amsterdam/design-system/blob/main/documentation/definition-of-done.md)**. + +- **[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur. + +- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. + +### Local development + +#### Install prerequisites You need to have the following tools installed to run Storybook locally: @@ -31,7 +105,7 @@ You need to have the following tools installed to run Storybook locally: - [Node.js and npm](https://nodejs.org/en/) - `pnpm`, `npm install -g pnpm` -## Install code editor +#### Install code editor You can use any editor you like, but if you use [Visual Studio Code](https://code.visualstudio.com/) we recommend the following extensions for this project: @@ -57,13 +131,20 @@ To enable correct validation and to fix lint/style errors on save, add this to y "editor.formatOnSave": true, ``` -## Run storybook +#### Run storybook - Install dependencies: `pnpm install` - Build the packages: `npm run build` - Run storybook: `npm start` -## Locally link this library to a local project +#### Adding a new component + +Scaffold all necessary files for a new component at once through `npm run plop`. +Enter the name of your component when prompted. +Answer the other prompts if applicable, otherwise use the defaults. +This will create files for the design tokens, CSS and React components, and React Stories. + +#### Locally link this library to a local project If you need to link your local version of this library (to test your unpublished changes, for example) to a local project, follow these steps: @@ -74,13 +155,13 @@ If you need to link your local version of this library (to test your unpublished - Run `npm link `. If you want to link multiple packages, separate the package names with a space. For example: `npm link @amsterdam/design-system-tokens @amsterdam/design-system-assets @amsterdam/design-system-react @amsterdam/design-system-react-icons`. - Be careful: you have to link all packages in the same namespace together. + **Be careful**: you have to link all packages in the same namespace together. Doing it one at a time will only link the last one. - Sometimes the local link is severed. Run `npm link @amsterdam/...` again if this happens. -## Licensing +### Licensing All Javascript, Typescript and style files should start with a license header. We use the EUPL-1.2+ license for these files. @@ -106,31 +187,18 @@ The license header looks like this: If the content of a documentation file is copied from another source, use the license of the original file. -## Git branching strategy and publishing - -We use [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) for this project. -All members of the [Amsterdam GitHub organisation](https://github.com/Amsterdam) are allowed to create features branches and open pull requests. -Only [the maintainers of this repository](./documentation/maintainers.md) are allowed to merge pull requests into the `main` and `develop` branches. -We currently do not have a workflow for contributors that do not work for the City of Amsterdam. -If you do not work for the City of Amsterdam and want to contribute to this repository, please contact the maintainers. +### Publishing -Package versioning and publishing is done through Lerna, by the maintainers of the repository. +Package versioning and publishing is done by the [maintainers](./documentation/maintainers.md) of the repository. Contributors do not need to increment versions. Contact the maintainers if you want to release a new version of a package. -## Adding a new component - -Scaffold all necessary files for a new component at once through `npx plop`. -Enter the name of your component when prompted. -This will create files for the design tokens, CSS and React components, and React Stories. - -## Publishing - -Only the [maintainers](./documentation/maintainers.md) can release new versions of our packages. -See the [publishing docs](./documentation/publishing.md) for more information. - -## Cooperation with NL Design System +### Cooperation with NL Design System This repository is part of the [NL Design System](https://nldesignsystem.nl/). When you contribute to this project you allow your contributions to be made a part of the NL Design System component library. For more information, please read about [their contribution model](https://nldesignsystem.nl/meedoen/estafettemodel/). + +## :pray: Credits + +This document is adapted from a template made by [@jessesquires](https://github.com/jessesquires). diff --git a/documentation/definition-of-done.md b/documentation/definition-of-done.md index 23f07f0e0c..5f36ef5bea 100644 --- a/documentation/definition-of-done.md +++ b/documentation/definition-of-done.md @@ -8,7 +8,6 @@ - You’ve added or updated the story of the component - Your code has the necessary tests written - The component’s style is imported in `css/src/index.scss` -- You’ve updated the [changelog](../CHANGELOG.md) unreleased section - The component can have an additional class name to enable restyling - The component has an EUPL-1.2+ license header, and all documentation has a Creative Commons 0 (CC0) license header From 19b86abb4176e2d9faad8ce14040fedd1612f73a Mon Sep 17 00:00:00 2001 From: alimpens Date: Fri, 19 Jul 2024 09:53:15 +0200 Subject: [PATCH 02/10] Update CONTRIBUTING.md --- .markdownlint.json | 3 ++- CONTRIBUTING.md | 24 ++++++++++++------------ 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index b077f0e1dd..6ab7bd17cd 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,4 +1,5 @@ { "default": true, - "MD013": false + "MD013": false, + "MD033": false } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 739492d370..147d71565b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,6 @@ # Contributing Guidelines - - ## Contents - [Code of Conduct](#book-code-of-conduct) @@ -12,8 +10,6 @@ - [Submitting Pull Requests](#repeat-submitting-pull-requests) - [Credits](#pray-credits) - - ## :book: Code of Conduct We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. @@ -29,11 +25,11 @@ TODO: add SUPPORT.md, https://docs.github.com/en/communities/setting-up-your-pro Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first. -### :lock: Reporting security issues +### Reporting security issues Review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). **Do not** file a public issue for security vulnerabilities. -### :beetle: Bug reports and other issues +### Bug reports and other issues For all other issues, you can [create an issue on GitHub](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue). @@ -66,8 +62,6 @@ Please follow these contribution guidelines from the NL Design System community: - [CSS](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-css--docs) - [Design Tokens](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-design-tokens--docs) - [HTML](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-html--docs) -- [npm package](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-npm-package--docs) -- [Storybook](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/nl-design-system-contributing-storybook--docs) Also follow our [CSS](./packages/css/documentation/coding-conventions.md) and [React](./packages/react/documentation/coding-conventions.md) coding conventions. @@ -101,11 +95,12 @@ If there is no design, or if you have questions about an existing design, please You need to have the following tools installed to run Storybook locally: -- Git +- [Git](https://git-scm.com/) - [Node.js and npm](https://nodejs.org/en/) -- `pnpm`, `npm install -g pnpm` +- [Pnpm](https://pnpm.io/), `npm install -g pnpm` -#### Install code editor +
+ Pro tip: VSCode extensions and linting on save You can use any editor you like, but if you use [Visual Studio Code](https://code.visualstudio.com/) we recommend the following extensions for this project: @@ -131,6 +126,8 @@ To enable correct validation and to fix lint/style errors on save, add this to y "editor.formatOnSave": true, ``` +
+ #### Run storybook - Install dependencies: `pnpm install` @@ -144,7 +141,8 @@ Enter the name of your component when prompted. Answer the other prompts if applicable, otherwise use the defaults. This will create files for the design tokens, CSS and React components, and React Stories. -#### Locally link this library to a local project +
+ Pro tip: Locally linking this library to a local project If you need to link your local version of this library (to test your unpublished changes, for example) to a local project, follow these steps: @@ -161,6 +159,8 @@ If you need to link your local version of this library (to test your unpublished - Sometimes the local link is severed. Run `npm link @amsterdam/...` again if this happens. +
+ ### Licensing All Javascript, Typescript and style files should start with a license header. From e20604f71f7fe0cff4ae699fd4d40d2a5ef1036f Mon Sep 17 00:00:00 2001 From: alimpens Date: Tue, 23 Jul 2024 14:27:41 +0200 Subject: [PATCH 03/10] Remove commented out section --- CONTRIBUTING.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 147d71565b..2ddc877cbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,6 @@ ## Contents - [Code of Conduct](#book-code-of-conduct) - - [Opening an Issue](#inbox_tray-opening-an-issue) - [Submitting Pull Requests](#repeat-submitting-pull-requests) - [Credits](#pray-credits) @@ -15,12 +14,6 @@ We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_OF_CONDUCT.md) if you haven’t already. - - ## :inbox_tray: Opening an issue Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first. From 689f9b1441aa5e7066b5e4375ddbd099878d478a Mon Sep 17 00:00:00 2001 From: Aram <37216945+alimpens@users.noreply.github.com> Date: Tue, 23 Jul 2024 14:28:31 +0200 Subject: [PATCH 04/10] Update CONTRIBUTING.md Co-authored-by: Vincent Smedinga --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ddc877cbc..ee020137a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,8 @@ Before creating an issue, check if you are using the latest version of the proje ### Reporting security issues -Review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). **Do not** file a public issue for security vulnerabilities. +**Do not** file a public issue for security vulnerabilities. +Review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). ### Bug reports and other issues From e53e7999e2688116a69ef4631630d45b4336248a Mon Sep 17 00:00:00 2001 From: alimpens Date: Tue, 23 Jul 2024 14:34:57 +0200 Subject: [PATCH 05/10] Expand section on reporting security issues --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ee020137a8..8817cd6e34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,9 @@ Before creating an issue, check if you are using the latest version of the proje ### Reporting security issues **Do not** file a public issue for security vulnerabilities. -Review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). +This may result in the vulnerability details being made public, creating an unsafe situation. +You can submit your report via [the Zerocopter Coordinated Vulnerability Disclosure (CVD) form](https://app.zerocopter.com/en/cvd/fc5dad1c-27ee-4571-880b-438dc672d178). +For more information, review our [Security Policy](https://github.com/Amsterdam/.github/blob/main/SECURITY.md). ### Bug reports and other issues From 0d6596b966d3e317c6522a598fea47597c4ccc14 Mon Sep 17 00:00:00 2001 From: Aram <37216945+alimpens@users.noreply.github.com> Date: Tue, 23 Jul 2024 14:38:51 +0200 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Vincent Smedinga --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8817cd6e34..44ac1b7856 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,7 @@ Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_O Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first. -### Reporting security issues +### Reporting a security issue **Do not** file a public issue for security vulnerabilities. This may result in the vulnerability details being made public, creating an unsafe situation. @@ -37,7 +37,7 @@ Follow these guidelines when doing so: - **Fully complete the provided issue template.** The bug report template requests all the information we need to quickly and efficiently address your issue. Be clear, concise, and descriptive. -## :repeat: Submitting pull requests +## :repeat: Submitting a pull request Before opening a pull request for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended approach for solving the problem in the comments for an existing issue. @@ -61,11 +61,11 @@ Please follow these contribution guidelines from the NL Design System community: Also follow our [CSS](./packages/css/documentation/coding-conventions.md) and [React](./packages/react/documentation/coding-conventions.md) coding conventions. -### Aligning with design/UX +### Aligning with UX design You can find the most up-to-date documentation on design and UX in the Storybook in this repository. -If you want to add a component, first check if it’s already included in our [Figma Library](). +If you want to add a component, first check if it’s already included in our [Figma Library](https://www.figma.com/design/9IGm6IdPUYizBNGsUnueBd). If there is no design, or if you have questions about an existing design, please contact . From 556a916fe845c7ccf4f0735bb771fd28ad43e73b Mon Sep 17 00:00:00 2001 From: alimpens Date: Tue, 23 Jul 2024 14:40:09 +0200 Subject: [PATCH 07/10] Link directly to issues section --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8817cd6e34..682ac25caa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ For more information, review our [Security Policy](https://github.com/Amsterdam/ ### Bug reports and other issues -For all other issues, you can [create an issue on GitHub](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue). +For all other issues, you can [create an issue on GitHub](https://github.com/Amsterdam/design-system/issues). Follow these guidelines when doing so: From 1e530fe50fa9a6b0f898ba878b0ab39ac473d1f7 Mon Sep 17 00:00:00 2001 From: alimpens Date: Tue, 23 Jul 2024 14:49:41 +0200 Subject: [PATCH 08/10] Start sentences on new line --- CONTRIBUTING.md | 46 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d32e1ba9a..e433a05a01 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ - [Code of Conduct](#book-code-of-conduct) - [Opening an Issue](#inbox_tray-opening-an-issue) -- [Submitting Pull Requests](#repeat-submitting-pull-requests) +- [Submitting Pull Requests](#repeat-submitting-a-pull-request) - [Credits](#pray-credits) ## :book: Code of Conduct @@ -16,7 +16,8 @@ Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_O ## :inbox_tray: Opening an issue -Before creating an issue, check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first. +Before creating an issue, check if you are using the latest version of the project. +If you are not up-to-date, see if updating fixes your issue first. ### Reporting a security issue @@ -31,15 +32,23 @@ For all other issues, you can [create an issue on GitHub](https://github.com/Ams Follow these guidelines when doing so: -- **Do not open a duplicate issue.** Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have. You may simply note "I have this problem too", which helps prioritize the most common problems and requests. +- **Do not open a duplicate issue.** + Search through existing issues to see if your issue has previously been reported. + If your issue exists, comment with any additional information you have. + You may simply note "I have this problem too", which helps prioritize the most common problems and requests. -- **Prefer using [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)**, not comments, if you simply want to "+1" an existing issue. +- **Prefer using [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)**, + not comments, if you simply want to "+1" an existing issue. -- **Fully complete the provided issue template.** The bug report template requests all the information we need to quickly and efficiently address your issue. Be clear, concise, and descriptive. +- **Fully complete the provided issue template.** + The bug report template requests all the information we need to quickly and efficiently address your issue. + Be clear, concise, and descriptive. ## :repeat: Submitting a pull request -Before opening a pull request for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended approach for solving the problem in the comments for an existing issue. +Before opening a pull request for non-trivial changes, +it is usually best to first open an issue to discuss the changes, +or discuss your intended approach for solving the problem in the comments for an existing issue. ### Git workflows @@ -71,19 +80,34 @@ If there is no design, or if you have questions about an existing design, please ### Pull request guidelines -- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. +- **Smaller is better.** + Submit **one** pull request per bug fix or feature. + A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. + **Do not** refactor or reformat code that is unrelated to your change. + It is better to **submit many small pull requests** rather than a single large one. + Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. -- **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing! +- **Coordinate bigger changes.** + For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. + Otherwise, you risk doing a lot of work for nothing! -- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it. +- **Prioritize understanding over cleverness.** + Write code clearly and concisely. + Remember that source code usually gets written once and read often. + Ensure the code is clear to the reader. + The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it. -- **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future. +- **Follow existing coding style and conventions.** + Keep your code consistent with the style, formatting, and conventions in the rest of the code base. + When possible, these will be enforced with a linter. + Consistency makes it easier to review and modify in the future. - **[Follow our Definition of Done](https://github.com/Amsterdam/design-system/blob/main/documentation/definition-of-done.md)**. - **[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur. -- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. +- **Promptly address any CI failures**. + If your pull request fails to build or pass tests, please push another commit to fix it. ### Local development From 7dac72d254e225da82e73eb27fdd8157220aef00 Mon Sep 17 00:00:00 2001 From: alimpens Date: Tue, 23 Jul 2024 14:58:17 +0200 Subject: [PATCH 09/10] Restructure doc --- CONTRIBUTING.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e433a05a01..725b559fcc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ - [Code of Conduct](#book-code-of-conduct) - [Opening an Issue](#inbox_tray-opening-an-issue) - [Submitting Pull Requests](#repeat-submitting-a-pull-request) +- [Local development](#computer-local-development) - [Credits](#pray-credits) ## :book: Code of Conduct @@ -109,9 +110,15 @@ If there is no design, or if you have questions about an existing design, please - **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. -### Local development +### Cooperation with NL Design System + +This repository is part of the [NL Design System](https://nldesignsystem.nl/). +When you contribute to this project you allow your contributions to be made a part of the NL Design System component library. +For more information, please read about [their contribution model](https://nldesignsystem.nl/meedoen/estafettemodel/). + +## :computer: Local development -#### Install prerequisites +### Install prerequisites You need to have the following tools installed to run Storybook locally: @@ -148,13 +155,13 @@ To enable correct validation and to fix lint/style errors on save, add this to y -#### Run storybook +### Run storybook - Install dependencies: `pnpm install` - Build the packages: `npm run build` - Run storybook: `npm start` -#### Adding a new component +### Adding a new component Scaffold all necessary files for a new component at once through `npm run plop`. Enter the name of your component when prompted. @@ -213,12 +220,6 @@ Package versioning and publishing is done by the [maintainers](./documentation/m Contributors do not need to increment versions. Contact the maintainers if you want to release a new version of a package. -### Cooperation with NL Design System - -This repository is part of the [NL Design System](https://nldesignsystem.nl/). -When you contribute to this project you allow your contributions to be made a part of the NL Design System component library. -For more information, please read about [their contribution model](https://nldesignsystem.nl/meedoen/estafettemodel/). - ## :pray: Credits This document is adapted from a template made by [@jessesquires](https://github.com/jessesquires). From dbc1be4574bd75ca1abc9853cf98b6003dbde511 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Tue, 23 Jul 2024 23:36:27 +0200 Subject: [PATCH 10/10] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 725b559fcc..ce2111a485 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ Follow these guidelines when doing so: - **Do not open a duplicate issue.** Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have. - You may simply note "I have this problem too", which helps prioritize the most common problems and requests. + Reacting with a ‘thumbs up’ helps us prioritize the most common problems and requests. - **Prefer using [reactions](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)**, not comments, if you simply want to "+1" an existing issue.