@gdwc/components/contributing.mdx

A library of generic web components that are accessible, framework agnostic, possible to style, and easy to use with data provided by Drupal

# Contributing

We'd love your help.

## Code of conduct

Be awesome to each other, have fun, and abide by the
[Drupal Code of Conduct](https://www.drupal.org/dcoc).

## Submitting Issues

This project is [managed on Drupal.org](https://www.drupal.org/project/gdwc).
New issues can be submitted in
[the project's issue queue](https://www.drupal.org/project/issues/gdwc).

## Code Contributions

If one hasn't been submitted already,
[submit an issue in the issue queue](https://www.drupal.org/node/add/project-issue/gdwc).
From the issue, follow Drupal's
[issue fork workflow](https://www.drupal.org/docs/develop/git/using-git-to-contribute-to-drupal/creating-issue-forks-and-merge-requests)
to fork the codebase, make changes, and create a merge request.

## Local Development Workflow

Prerequisites: steps below assume that you have [NodeJS](https://nodejs.org/)
installed. We recommend using [NVM](https://github.com/nvm-sh/nvm) to manage the
NodeJS version on your local system.

In order to prepare your system for contribution you'll need to complete this
checklist:

1. Run `nvm use` to switch to the expected version of npm. Run `nvm install` if
   you need to update your npm.
2. Run `npm i` to install dependencies.

This project currently uses
[Storybook for Web Components](https://storybook.js.org/docs/web-components/get-started/introduction)
as a development environment. After installing, you can launch storybook in
development mode by running:

    npm run storybook

Changes made to components or stories will live reload in your browser.

To create a production build, run:

    npm run build

Components are bundled for production using [Vite](https://vitejs.dev/).

## Linting

Staged files will be linted and formatted prior to commit using lint-staged and
husky. It is also possible to run these tasks manually using the following
commands:

    npm run lint
    npm run format

VSCode users can also format code on save using the
[Eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
and
[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
extensions. These extensions will be suggested when loading the project if they
have not already been installed. An example settings file is included in
`.vscode/example.settings.json`. Save this file as `.vscode/settings.json` or
incorporate the contents into your existing settings.json file to enable format
on save in your project.

## Component Scaffolding Script

To create a new component, run:

    npm run create-component

You will be prompted to provide an element name (e.g. my-element) and a
description. After responding to the prompts, a new custom element and story
will be created. Components created using this script will be pre-configured to
take advantage of features of this library like theming via css custom
properties.

## Project Structure

- **Components** - components live in a top level directory with the same name
  as the custom element. Ex: `/gdwc-menu`
- **Stories** - stories live alongside the custom element and have a .stories.js
  extension.
- **Documentation** documentation lives in the `/stories/docs` directory.

## Styling API

Approaches to exposing component styling hooks are outlined in the
[Styling API documentation](/?path=/story/overview-styling-api--page).

## Editing documentation

This storybook contains two main sources of documentation and each requires a
slightly different approach to editing.

- **Component Documentation** - component documentation lives in the related
  story file. Ex: `/stories/gdwc-menu/gdwc-menu.stories.js`. The main focus here
  is documenting all of the possible arguments for each component - properties,
  slots, shadow parts, etc. For more information on writing stories, consult
  [the Storybook documentation](https://storybook.js.org/docs/web-components/writing-stories/introduction).
- **General Documentation** - general documentation lives in markdown files in
  `/stories/docs`. The existing files can be edited or new files can be created
  to cover new topics. The contents of these files can be standard Markdown or
  can use [MDX](https://storybook.js.org/docs/web-components/writing-docs/mdx).

## Publishing

Updated versions of this library are currently published to NPM manually. As are
updates to the Storybook documentation hosted on Netlify.