Skip to content

Latest commit

 

History

History
263 lines (184 loc) · 12.3 KB

CONTRIBUTING.md

File metadata and controls

263 lines (184 loc) · 12.3 KB
Raw

Contributing guidelines

  1. CSS
    1. Vue
    2. BEM
    3. ITCSS
  2. Vue app
  3. Testing
    1. Unit tests
    2. Visual regression tests
  4. Linting
  5. Build
  6. Submitting changes
    1. Creating a PR
    2. Code Review
    3. User Acceptance Testing
    4. Merge conditions
  7. Release
  8. Reporting a problem or requesting a change
    1. How to report a bug
  9. 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 members for Eburyonline. Check the VISION 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 (PR) from the JIRA issue and move your issue to the correct status.
  5. Manage the User Acceptance Testing (UAT) according to the guidelines and update the JIRA issue status.
  6. During the Code Review phase the reviewers could propose changes; and it means possible changes and new commits.
  7. When the 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.

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/

/* 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:

npm link

3. On your Vue app folder run:

npm link @ebury/chameleon-components

4. All components are exported by name so you can import them with:

import { ComponentName } from '@ebury/chameleon-components';

Testing

Unit tests

To run your tests:

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

Visual regression tests

To run visual regression tests:

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.

// 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 cypress-io/cypress#3090 for reference.

NOTE2: Because of another bugs in Cypress, visual regression tests can run only in headless mode. See cypress-io/cypress#3324 for reference.

To configure visual regression tests for the story, you can use storybook parameters to do so:

{
  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).

// update in package.json
{
  "test:visual:all": "cypress run --env updateSnapshots=true --env failOnSnapshotDiff=false ..."
}

Linting

To lint and fix errors in files:

npm run lint

Build

To build your Storybook:

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 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 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 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 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.
  • 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 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.

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).
    • If it is detected during the Software Development Life Cycle (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).

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!