Skip to content

Latest commit

 

History

History
233 lines (151 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

233 lines (151 loc) · 11.7 KB
Raw

🔨👷 Contributing

Table of Contents

Dependencies

  • Node (>= v16)
  • npm CLI (>= v7)

We recommend using nvm. It is a great tool for switching between Node versions

Getting Started

Before you get started

Before you get started we STRONGLY recommend that you save yourself a lot of time by scheduling a pre-design. Our PRs that had a predesign went smoothly and the ones that didn’t had lots of changes. Please schedule the predesign. You can request a predesign session in the Modus Web Components chat group

To prepare for the predesign session please:

  • Bring your link to the approved Modus Figma designs (we only contribute Figma approved components)
  • Bring documentation on the component

Running the App

If this is your first time in the project, navigate to the ./stencil-workspace directory and run npm install to download third-party packages.

Once you've installed the project's packages, run npm run build. After the build is complete, run npm start. A development environment will start up with the contents of index.html. This file provides a place to render components for development and end-to-end testing.

All web components are located under the ./stencil-workspace/src/components directory.

Global SCSS files are available to provide Modus colors, variables and functions for component styling.

Implementation

Stencil web component implementation details can be found in their Framework Integration Docs.

Available Scripts

All npm scripts are run from the ./stencil-workspace project directory.

npm install - Install third-party packages

npm start - Compile and run the Stencil development site

npm run build - Compile the component library

npm run test - Run the unit and e2e tests

npm run test.watch - Run the unit and e2e tests with auto re-run on changes

npm run generate - Start the interactive Stencil component generator

npm run lint - Run ESLint to find problems with JS, TS and SCSS code

npm run start-storybook: Build and run the Storybook documentation site. Note: You will need to manually install the packages in ./stencil-workspace/storybook before running this command

Submitting Issues

Whether you're contributing directly to the code or have suggestions, submitting an issue through GitHub is needed for referencing changes. Please submit change items as an Issue here.

If the issue's considered a bug, add the 'bug' label to the issue.

Also add a priority level label to the issue. The priority options are low, medium, and high. If you are unsure of its priority, reach out to one of the developers for their opinion.

Modus core team will be looking at the open issues, analyze them, and provide guidance on how to proceed. Contributors are welcome to participate in the discussion and provide their input on how to best solve the issue, and even submit a PR if they want to. Please wait until the issue is ready to be worked on before submitting a PR, or you can reach out to the core team if it is time bound. For trivial things, or bugs that don't change the expected behaviors and UI, you can go ahead and make a PR.

Technologies

Stencil

Stencil is a web component compiler. Web components is a suite of JavaScript technologies that let you register a component directly with the browser. This means that the component can be used in any web application. It comes packed with a dev server and live re-rendering. We are using it to build out the components.

Storybook

Storybook is a tool for developing components in isolation. It also provides a framework for developing component library documentation sites. We are using it to document our components.

npm

We are hosting this package on both the @trimble-oss GitHub npm registry, and the public npm registry.

Running Locally

To get this application up and running, there are just two commands needed:

  • Run npm install
  • Run npm start

Note: The ./stencil-workspace project directory is the source of truth for this component library. This is where all component changes will take place. The other directories are generated.

Developing a Component

Stencil gives us a dev server to work with out of the box. Using this dev server is our recommended way for developing on these components. When running npm start, the ./src/index.html is served up. To start developing on a component, you must add the component to the index.html using its HTML tag. After manually adding the component to the body of the index, you're able to add arguments to its attributes in the markup. Properties that cannot be accessed through attributes can be set in the <script> tag of the index.

The components are automatically registered with the browser in this environment, so all you'll need to do is reference its tag like so:

...
<body>
  <modus-alert message="Hello, dev environment!"></modus-alert>
</body>
...

You can find more in depth examples of how these attributes and properties are set on the Modus Web Components Storybook site.

Style Guide

This project follows Modus Styleguide for UX guidelines and uses Stencil's Style Guide for how to structure the code components.

Testing

Each of the components has unit and end-to-end (e2e) tests. Both of these test types use Jest as the JavaScript testing solution. The e2e tests also use Puppeteer to test the components in an actual browser (giving more realistic results).

Unit tests focus on testing a component's methods in isolation. For example, when a method is given the argument X, it should return Y.

E2e tests focus on how the components are rendered in the DOM and how the individual components work together. For example, when my-component has the X attribute, the child component then renders the text Y, and expects to receive the event Z.

For more information about Stencil's testing, and a better distinction between the unit and e2e tests, check out the testing docs here.

Run the tests with npm run test.

To run a specific test, run stencil test --spec --e2e --silent [test file name].

Debugging Tests

Before running the test.debug script, make sure to add the file you want to debug to the end of the script line. For example, "stencil test --spec --e2e --watchAll --devtools -- modus-autocomplete.e2e.ts". This will open Chrome dev tools for debugging, and run only the Autocomplete e2e tests.

You can add the following code to the test file to pause the test at a specific point while it's running in Chrome dev tools: page.evaluate(() => { });

Considerations

When submitting or reviewing contributions to the Modus Web Components library (MWC), it is important to keep code quality in mind. Check out the Considerations doc for more information.

Making Changes and Submitting a PR

  1. Before working on an issue, the repository should be forked with intent to contribute to the parent repository.
  2. Branch from your fork using the naming convention issue-{#}/{description}. For example, issue-123/my-bug-fix.
  3. Make your changes. Be sure to update or add relevant tests!
  4. Run npm run lint, npm run build, and npm run test. If all is well, continue.
  5. If there is any change to the library's API, update the Storybook documentation under ./storybook/stories.
    • To run the Storybook site, cd into the directory and run npm run storybook. The library build will need to be up to date. The changes to the site will be deployed upon the PR merge to main.
  6. Once all of your changes have been made, squash your commits down to a singular commit with a relevant message.
  7. Submit your PR with your branch as the head, and the @trimble-oss/modus-web-components main branch as the base.
    • Don't forget to link your relevant issue in the PR description.

Changelog

The release notes can be viewed on the GitHub Releases page.

Semantic Versioning

This project uses the following semantic versioning convention for the repository and changelog entries. Given a version number [MAJOR.MINOR.PATCH], increment the following:

  1. Major: to make incompatible API changes - updates containing new dependencies.
  2. Minor: to add functionality in a backwards compatible manner.
  3. Patch: to make backwards compatible bug fixes. Example: Version 1.0.0 has a function added in accordance with a minor version update. The new version will be 1.1.0. See: semver.org.

Releasing Framework Outputs

Before releasing any of the framework outputs, the targeted version of the Modus Web Components should be successfully released.

Angular

The Angular component integration can be found under the ./angular-workspace directory.

  1. Update ./angular-workspace/ng-<version-number>/projects/trimble-oss/modus-angular-components/package.json's:
    1. Dependency on the Modus Web Components library to the targeted version
    2. The package's version to reflect the targeted version
  2. From the ./angular-workspace/ng-<version-number>/projects/trimble-oss/modus-angular-components directory, run npm i.
  3. From the ./angular-workspace/ng-<version-number>/projects/trimble-oss/modus-angular-components directory, run npm run build.
  4. From the newly generated ./angular-workspace/ng-<version-number>/dist/trimble-oss/modus-angular-components directory, run npm publish.

React

The React component integration can be found under the ./react-workspace directory. Each version of React has a library react-17 and a test harness app test-react-v17

  1. Update ./react-workspace/react-<version-number>:
    1. Dependency on the Modus Web Components library to the targeted version
    2. The package's version to reflect the targeted version
  2. From the ./react-workspace/react-<version-number> directory, run npm i.
  3. From the ./react-workspace/react-<version-number> directory, run npm run build.
  4. From the ./react-workspace/react-<version-number> directory, run npm publish.

As an alternative to publish, this can be also consumed in a local react application using npm link or generate a tarball file using npm pack.

Recommended

Import the React library in ./react-workspace/test-react-v<version-number> for testing the components locally, refer to src/App.tsx file for more details on how to test the components.