Skip to content

Latest commit

 

History

History
213 lines (147 loc) · 9.43 KB

CONTRIBUTING.md

File metadata and controls

213 lines (147 loc) · 9.43 KB
Raw

Contributing to Forge

We are very open to contributions to the Forge component library! There are many forms of contribution, from documentation updates and creating issues to bug fixes and features. No matter your contribution, we only ask that you follow our contribution guidelines defined below. Thank you for helping to move this project forward!

General Contributing Guidelines

Forge is an open source project that accepts contributions from community members.

Want to contribute? Great! Please read on for more details.

If you’ve never contributed to an open source project before, take a look at GitHub’s Contributing to Open Source on GitHub to learn some of the basics.

Development Process

We strive to make developing the Forge components library as frictionless as possible, both for ourselves and for our community. This section should get you up and running working on the Forge codebase.

Before beginning development, you may want to read through our overview on architecture and best practices to get a better understanding of our overall structure.

Setting up your development environment

Ensure you have the latest LTS version of node installed. We use LTS versions of node in our CI environments to validate builds and run unit tests. Compatibility with your local development environment is important.

To get started, clone the repository:

git clone https://github.com/tyler-technologies-oss/forge.git

Navigate to the project root, and install dependencies:

npm install

This project contains a dev site built using Vite to make development faster and easier.

npm start

We also use Storybook for docs and local development. This helps us build and maintain component demos (stories) and the corresponding documentation for each component. To start up the Storybook environment locally, run the following command:

npm run storybook

New Storybook versions are deployed for every pull request to help reviewers easily validate changes. The main Storybook deployment is updated when changes are merged to main. Storybook is linked in the main Forge documentation site to help keep documentation up to date.

Building the library

To run a production build of the library (which generates a distribution npm package directory), please run the following command:

npm run build

This project uses the forge CLI to build and manage your project. The equivalent command is forge build

A successful build-command output is found in the dist/release/@tylertech/forge directory.

Please validate that your build runs locally before pushing changes to remote to avoid iterating on build errors in the CI environment.

Linting

To ensure proper code style and formatting, we use ESLint and stylelint in this project for linting javascript/TypeScript and CSS/Sass respectively. Linting is executed when running the build command and as a pre-commit hook. The linter can be run at any time with the npm run lint command.

Running unit tests

This project uses Karma and Jasmine as the unit testing environment.

  • To run tests over the whole project, use command: npm run test.
  • To run tests over a single component, use command: forge test component <component name> [--browser chrome] [--port <port number>]

It's important that you add/update tests when submitting changes to the library. The tests are validated in the CI environment.

You can view the code coverage report by running the following command:

npm run serve:coverage

This will open your default browser to the code coverage generated by the most recent test run. Code coverage is instrumented by istanbul.

Developing inside a container

This project supports VS Code DevContainers to help streamline and standardize the local development process. To get started with DevContainers you'll need to ensure you're running the following on your local machine:

  • Docker
  • Visual Studio Code
  • VSCode Remote Development extension pack
  • GITHUB_TOKEN environment variable configured

See these getting-started instructions for additional details.

Once setup, VS Code should prompt with a notification that a DevContainer config file is recognized and suggest re-opening within a container.

You can create a new token GITHUB_TOKEN at https://github.com/settings/tokens with the read:packages. This needs to be added to your environment through your .bashrc, .zshrc or windows path environment settings.

Manually open project in container

  1. Open project folder in VS Code
  2. Open in container
  3. Wait for devcontainer to build (~5 minutes)
  4. Serve the dev site to test the library: npm start
  5. To build the npm package, run the following: npm run build

For more information on starting a development environment within a container see Developing inside a Container

DevContainers Performance Notes

When opening this project in a DevContainer on a Windows or Mac operating system, you may experience poor disk performance due to their use of bind mounts. See the following article for additional information and tips on how you might improve disk performance.

In situations where you're unable to make use of the WSL2 filesystem (Windows), or where you're using macOS, you'll experience the best performance by making use of the Remote-Containers: Clone Repository in Container Volume command within VS Code. See this article for more information.

Clone in containers

  1. Open VS Code
  2. Clone repository in container
  3. Wait for devcontainer to build (~5 minutes)
  4. Serve the dev site to test the library: npm start
  5. To build the npm package, run the following: npm run build

Note: if you make any package changes and want them to persist you may need to rebuild the container

Testing in a container

  • To run tests over the whole project, use command: npm run test:container.
  • To run tests over a single component, use command: forge test component <component name> --no-sandbox [--browser chrome] [--port <port number>]
  • To connect via Chrome visit chrome://inspect/#devices and select the correct instance

Issues and Bugs

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to the GitHub repository.

Pull requests are even better! Propose a fix with a pull request, and link it to the issue!

Feature or Component Requests

We are always interested in improving the Forge library. Whether it's a new feature for a component, an improvement to the developer experience, or an entirely new component, we look forward to your engagement.

The Forge team uses a governance model to discuss enhancements to the library. This is where we will discuss the feature or new component and make sure it aligns with our overall vision.

When creating a new issue on this repository, you will choose from one of the corresponding issue templates and provide the requested information. From there we will work with you to iron out the details of your proposal and then determine timeline and resources needed to implement the feature.

Submitting Pull Requests

The best way to make an impact is by creating code submissions. Pull requests should be "solutions" to GitHub issues. If there is not an existing GitHub issue, please start by creating one before submitting a pull request.

When creating a new pull request, please provide as much information as you can by filling out the pull request template. This will help speed up the process of getting your changes reviewed and merged.

This project uses Auto for its CI/CD automation. Please familiarize yourself with Auto. Release versions are controlled by labels on Pull Requests.

Commit message format

This project uses a pre-commit hook (via husky) to ensure a proper commit message format is provided for all commits. This format follows the conventional commit format described here.

Note: if you're on MacOS/Linux and use NVM, you may run into an issue with the pre-commit hook. See here for information about how to resolve this issue.