# Contributing guidelines 1. [CSS](#css) 1. [Vue](#vue) 2. [BEM](#bem) 3. [ITCSS](#itcss) 2. [Vue app](#vue-app) 3. [Testing](#testing) 1. [Unit tests](#unit-tests) 2. [Visual regression tests](#visual-regression-tests) 4. [Linting](#linting) 5. [Build](#build) 6. [Submitting changes](#submitting-changes) 1. [Creating a PR](#creating-a-pr) 2. [Code Review](#code-review) 3. [User Acceptance Testing](#user-acceptance-testing) 4. [Merge conditions](#merge-conditions) 7. [Release](#release) 8. [Reporting a problem or requesting a change](#reporting-a-problem-or-requesting-a-change) 1. [How to report a bug](#how-to-report-a-bug) 9. [Thanks!](#thanks) Hi there! We’d love your help if you're interested in contributing to Chameleon. Chameleon is the design system developed by the [Online team](https://fxsolutions.atlassian.net/wiki/spaces/TEAM/pages/119543461/ONL) members for Eburyonline. Check the [VISION](VISION.md) for the project as well as the guidelines below to contribute. These are the steps to contribute with a new change to this repository: 1. Create an **issue** in JIRA in your project board, complete the required information, add the issue to your current sprint and set the status to the equivalent to "in progress". 2. Create a **branch** in the repository from `master` branch. The name of the branch starts with the JIRA issue identifier and some optional suffix. For example, for issue `ONL-123`, the branch can be named `ONL-123-task`. 3. In every **commit** messages, include a prefix `[ONL-123]` and then a descriptive message. Try to commit frequently and doing commits by atomic changes. 4. When your change is ready to be reviewed, create a [Pull Request](#creating-a-pr) (PR) from the JIRA issue and move your issue to the correct status. 5. Manage the [User Acceptance Testing](#user-acceptance-testing) (UAT) according to the guidelines and update the JIRA issue status. 6. During the [Code Review](#code-review) phase the reviewers could propose changes; and it means possible changes and new commits. 7. When the [Merge conditions](#merge-conditions) are fulfilled, you can **merge** the code from the PR following the **squash** strategy and **close the issue** in JIRA. For the development of @ebury/chameleon-components, we use storybook [Storybook](https://storybook.js.org/). ## CSS For chameleon components, we use ITCSS architecture with BEM naming, TailwindCSS for Utilities, and PostCSS as a postprocessor. Please don't add any CSS styles without following the rules below. ### Vue The single-file Vue components should not use scoped styles as is not necessary since we follow BEM. ### BEM A methodology on how to name your classes http://getbem.com/introduction/ ```css /* Block component */ .btn {} /* Element that depends upon the block */ .btn__price {} /* Modifier that changes the style of the block */ .btn--orange {} .btn--big {} ``` ### ITCSS https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/ Following the ITCSS the file CSS structure should look like 1. Settings - Global CSS variables, e.g. color definitions and maximum widths. 2. Tools - Mixins, functions etc. 3. Generic - CSS resets, normalizecss and font-faces. No classes, IDs, or elements. 4. Elements - Only base HTML elements like p, h1, h2, div etc. 5. Objects - Layouts and grids. 6. Components - Classes for specific UI components, most likely you want to add your classes in here. 7. Utilities - Utility classes generated by TailwindCSS. ## Vue app If you would like to consume and test the behaviour of your newly developed components in your local Vue app: 1\. You must create a symlink that will connect the two repos via the npm global folder. On chameleon-components folder run: ```sh npm link ``` 3\. On your Vue app folder run: ```sh npm link @ebury/chameleon-components ``` 4\. All components are exported by name so you can import them with: ```js import { ComponentName } from '@ebury/chameleon-components'; ``` ## Testing ### Unit tests To run your tests: ```sh npm run test ``` The test coverage is set to 100%, but if you think the test for a particular piece of code is not necessary, then mark the code with `/* c8 ignore */` flags and get prepared to defend it during the PR. This process gives us visibility that every exclusion has been approved. For more information see the [c8 docs](https://github.com/bcoe/c8/blob/main/README.md) ### Visual regression tests To run visual regression tests: ```sh make cypress-integration ``` You can also just run `make cypress-install` and then `make cypress-run` as many times as you want. It will skip the installation part before each run. To run tests only for specific story, you can use `storyIdFilter`. The ID of the story can be found in the URL of the storybook, e.g. "Icon / basic" story has ID `icon--basic`, "Layout / Container / with navigation" has ID `layout-container--with-navigation`. `storyIdFilter` accepts any regex. ```json // update in package.json { "test:visual:all": "cypress run -e storyIdFilter=icon ..." } ``` Visual regression tests run in headless Chrome and Firefox. NOTE: Because of bugs in Cypress, visual regression tests cannot run All Specs mode. See https://github.com/cypress-io/cypress/issues/3090 for reference. NOTE2: Because of another bugs in Cypress, visual regression tests can run only in headless mode. See https://github.com/cypress-io/cypress/issues/3324 for reference. To configure visual regression tests for the story, you can use storybook parameters to do so: ```js { visualRegressionTests: { disable: false, // false by default, if set to true, it will skip the story. waitOn: '.search-results', // wait on this element to appear before taking snapshot (cy.get(waitOn)). defaults to #root snapshotElement: '.search-results', // take snapshot of this element only. defaults to entire viewport controls: { // you can run the tests using custom controls, if the story supports them. large: { size: 64 }, // "large" is the name of test, it will be used in the name of the snapshot file. "size" is the prop of the knob 'type-error': { type: 'error' }, }, }, } ``` To update screenshots, you can run `cypress run` command with flags `--env updateSnapshots=true --env failOnSnapshotDiff=false` (do not commit these flags). ```json // update in package.json { "test:visual:all": "cypress run --env updateSnapshots=true --env failOnSnapshotDiff=false ..." } ``` ## Linting To lint and fix errors in files: ```sh npm run lint ``` ## Build To build your Storybook: ```sh npm run build-storybook ``` ## Submitting changes These are the steps to contribute with a new change to this repository: ### Creating a PR A **Pull Request** (PR) is the method of submitting contributions to the project. The project uses Github for PR management and can be created from JIRA issues. The PR is a process for peer review by code maintainers and relevant developers involved in the changes. Considerations during the Pull Request creation: * The **destination branch** of the Pull Request must be `master` branch. * The **title** follows the format: [issue-id] type: Title of the issue. (i.e. `[ONL-123] chore: Changing the documentation`) Where the type of the commit follows [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. * Update the **description** to include a descriptive text for changes with notes for the reviewers and screenshots if necessary. * The default **reviewers** must be the code owners defined in the [CODEOWNERS](CODEOWNERS) file and you must include also some code owners related with third party services, when these changes affects them. Share the PR in [#online-reviews](https://app.slack.com/client/TFMC43PH7/C0132DEVAPM) Slack channel to be reviewed by Online team members. * Mark the option "close branch after the Pull Request is merged". ### Code Review **Code Review** is an integral process of software development that helps identify bugs and defects before the testing **phase**. We use the Pull Request (PR) mechanism in Github to do this process. These are the considerations for the code review phase: * The PR is considered **approved** when **some code owner** have approved the PR. * The comments can be done at PR level or at detailed level. * The comments can be in different levels of relevance: **mandatory** or **optional**. * The mandatory changes must have a associated **task** in the Pull Request view. * All the mandatory changes must be changed and the associated tasks marked as **done**. * The code owners review the manual checks for **Style guide** of the project. * If the change is rejected by the code owners and there is not possibility of modifications, the PR will be marked as **declined**, and the process do not continue. If it can be modified, the Pull Request should not be declined, only commented with mandatory changes. * The code review phase is considered **finished** when all the mandatory changes are done and it is approved. ### User Acceptance Testing User acceptance testing **User Acceptance Testing** (UAT) is a process to verifying that a solution works for the user. In our process, we will use the [vercel](https://vercel.com) app that we have installed in our repository, on the pull request the app will give as a link with the solution working, once the code review is approved you will need to add this link to the ticket before you pass the ticket to the **DONE** status. ### Merge conditions Before merging a code in a **Pull Request** to the `master` branch, it is required to comply with **all** the next conditions: * The **Code Review** phase has **finished**. * The **Build in GH Actions** (CI) process marks the PR as **green**. * There are no **merge conflicts**. * The branch must be **updated** with the latest commit of `master` branch. * The strategy that must follow the PR will be **squad** ## Release When a PR passes all the **Style guide** and is before is merged to the `master` branch, a new version of Chameleon can be released following the next steps * You must bump the version of chameleon, it can be done with this script `npm version [patch|minor|major]`. * You should publish the code with the new version in **npm**, use this script to do it `npm publish`, if you are not able to publish because you don't have permission ask one of the [CODEOWNERS](CODEOWNERS). * `npm version` creates a commit with updated `package.json` that you need to push to your branch. Do not push the created tag because the merge squashes the commits and the created tag will be pointing at squashed ones. Delete the tag before push using `git tag -d v$(npm view . version)` and recreate it later in `master` after the changes get merged. * Merge the branch to `master` and tag the latest commit there with the same version as in `package.json` you just merged. Use the script `git tag v$(npm view . version)`. * Push the tag to the repo using command `git push origin v$(npm view . version)`. * Optional: Create a [github release](https://github.com/Ebury/chameleon/tags) from the tag. Write a few notes about the release and breaking changes. ## Reporting a problem or requesting a change If you want to report a problem or request some change you can report an issue to [Eburyonline JIRA project board](https://fxsolutions.atlassian.net/jira/software/c/projects/ONL/issues?filter=allissues). ### How to report a bug Depending on the kind of reporter, and when it is detected bugs will be reported as follows: * If you are a **contributor or code owner** and detect a bug in this project, you must create a JIRA issue in your board with task type **defect** (see [here](https://fxsolutions.atlassian.net/wiki/spaces/PRODUCTS/pages/123095173/Bugs+and+e2e+philosophy)). * If it is detected during the Software Development Life Cycle [(SDLC)](https://fxsolutions.atlassian.net/wiki/spaces/PRODUCTS/pages/42795535/SDLC), you must create it as subtask of the main task. * If it is detected during a release, as subtask of the release task. * In other cases, as task. * **Support team members** will create the JIRA issue as **bug** and communicate with the code owners if the bug comes from production environment (see [here](https://fxsolutions.atlassian.net/wiki/spaces/PRODUCTS/pages/123095173/Bugs+and+e2e+philosophy)). ## Thanks! Thanks! Contributing to Chameleon should be easy. If you find any of this hard to figure out, let us know so we can improve our process or documentation!