CONTRIBUTING.md

Contributing

This document outlines the guidelines and best practices to get started contributing to ARC.

We welcome all contributions and engagement with the ARC design system.

ARC is built using LIT web components and is built on top of the Web Components standards. Every component is a native web component, with the power of interoperability. Web components work anywhere you use HTML, with any framework, or none at all. This makes using ARC ideal for building shareable components, or maintainable, future-ready sites and apps.

• Workspace
• Development Environment
• Build System
• Development Guidelines
  • Directory Structure
  • Local Development Server
  • Unit Tests
  • Documentation
  • Formatting and Linting
• Infrastructure
• Guides

Workspace

This worksapce is a monorepo containing all packages and playgrounds that relate to the ARC design system. The following directory structure is used:

├── assets              # Shared assets for storybook and playgrounds
├── infrastructure      # Infrastructure managed by Terraform
├── packages
│   ├── components      # @arc-web/components package source
│   └── react           # @arc-web/react package source
└── playgrounds
    ├── angular         # Angular + ARC playground
    ├── javascript      # Vanilla Javascript + ARC playground
    ├── node-ssr        # NodeJs SSR + ARC playground
    ├── react           # React + ARC playground
    └── vue             # Vue + ARC playground

NX is used as a monorepo management for the Javascript ecosystem within this workspace.

Development Environment

Switch to the provided develop environment using the following command:

nix develop

Install dependencies using the following command:

npm install --legacy-peer-deps

See relative project.json for each package or playground for available NX runnable targets.

Build System

Nix is used for all builds - please see our flake.

Development Guidelines

All development contributions should adhere to the following guidelines:

Directory Structure

The following directory structure should be followed when creating simple components:

└── packages
    └── components
        └─── src
           └── components
               └── foo
                   ├── ArcFoo.ts              # Component class implmentation
                   ├── arc-foo.stories.ts     # Storybook stories for component
                   ├── arc-foo.styles.ts      # Styles for component
                   ├── arc-foo.test.ts        # Tests for component
                   └── arc-foo.ts             # Component element registation

More complex compnents may also adher to the following:

└── packages
    └── components
        └─── src
           └── components
               └── foo
                   ├── constants
                   │   ├── FooConstants.test.ts    # Tests for constants
                   │   └── FooConstants.ts         # Constants for component
                   ├── ArcFoo.ts                   # Component class implmentation
                   ├── arc-foo.documentation.mdx   # Storybook documentation for component
                   ├── arc-foo.stories.tsx         # Storybook stories for component
                   ├── arc-foo.styles.ts           # Styles for component
                   ├── arc-foo.test.ts             # Tests for component
                   └── arc-foo.ts                  # Component element registration

Local Development Server

During development use the following command to start a local development server in any of the playgrounds:

npx nx run <angular-playground | lit-playground | react-playground | vue-playground | vanilla-playground | node-playground>:serve

Or start the storybook development server with:

npx nx run components:storybook:serve

Source code chanages will be hot reloaded in the browser making any of the above commands ideal for local component development.

Unit Tests

Unit tests must be written for all components and can be run using the following command:

npx nx run-many --target test

Documentation

Every component requires the following documentation:

• Docstrings for all public methods and properties
• Storybook stories for all use cases
• Storybook documentation (auto-generated from stories for simple components)

Formatting and Linting

Format this workspace with:

npx nx format:wrtie

Run all lint targets using:

npx nx run-many --target lint

Commit Messages, Branches and Pull Requests

Commit messages must adhere to the Conventional Commits specification and branches much follow the Gitflow branching model.

Pull requests will be squash merged by default the core maintainers, once accepted and approved, please ensure your PR title and description follow the Conventional Commits specification to ensure the correct changelog is generated. More complex PR's may be merged using the merge commit strategy.

Link any commits, issues and pull requests to the relevant Jira ticket, if applicable.

Infrastructure

The ARC project infrastucture is spread across the following deployment nodes:

C4Deployment
  Deployment_Node(browser, "Web Browser"){
    Container(browser-documentation, "Documentation", "Storybook")
  }

  Deployment_Node(azure, "Azure") {
    Deployment_Node(azure-resource-group-arc, "Azure Resource Group - ARC") {
      Container(azure-static-site-documentation, "S3 - Frontend", "Azure Static Site")
      Rel(browser-documentation, azure-static-site-documentation, "")
    }
  }

Loading

Guides

Release

1. Update all package package.json versions
2. For each package built it with Nix: nix build .#<package-name>
3. For each package the release to NPM: cd result && npm publish
4. Create a release commit, tag and GitHub release