CONTRIBUTING.md

Contributing to Groundwork Water

Thank you for your interest in contributing to Groundwork Water! Your help is appreciated. Please follow these guidelines to ensure a smooth contribution process.

To contribute to Groundwork-Water you must be a member of the U.S. Army Corps of Engineers Water Management.

How to Contribute

Note: You must have nodejs installed and in your path!

1. Submit an issue

   1. Create an issue as bug or feature/etc
   2. If you wish to work the issue, ask for it to be assigned to you. If you can, assign it to yourself.

2. Retrieve the Repository

   • Non Core Developers:
     • Create your own fork and clone it locally.
   • Developers (Ask for access):
     • Clone the repository directory

3. Create a Branch

   NOTE: Try to use the "create branch" feature on the right sidebar of GitHub in the issue's given page

   If Not: Use a descriptive branch name for your feature or fix:

   git checkout -b feature/your-feature-name

   Or use VSCode to create the branch after step 2

4. Install the root and docs packages

   For a first-time setup, install the required dependencies for both the library and documentation site.

   From the root of the project, run:

   npm install

   Then install the docs dependencies:

   cd docs
   npm install

5. Build the library and run the docs locally NOTE you must rebuild the library after changing library source files (.ts or .tsx) for those changes to appear in the docs site. If you are only changing documentation files, you can run the docs site without rebuilding the library. This will use the link command to link the local library so that you can make changes to the library and see those live on your local system without having to deploy those changes to NPM.

   For a first-time setup or after changing library source files (.ts or .tsx), run the following from the root of the project:

   npm run build-local
   
   cd docs
   npm run dev

   For later docs-only work, you can usually start the docs site from the /docs directory:

   npm run dev

   Read more below under workflow recommendations for how the local library linking works.

6. Make Changes
   Make your changes and attempt to commit one idea at a time within your branch to make it easier in review.

   For example: If you need to rename a file or move it. You would do that, then commit that singular change. Or if you were adding a page path to the docs, you would make all the tweaks across the files to initialize the page and add it to the routes for that commit.

7. Run Tests
   Use the local dev instance to manually test your changes and ensure they work. We use a form of Dogfooding where we link the library to the documentation. Start the documentation locally. Then call the library itself in that documentation.

8. Commit Changes
   Use meaningful commit messages:

   git commit -m "Create path structure for useCdaBlob docs"

9. Version your Code
   Run changesets to version your code.
   To do this run:
   npx changeset

   If you are working on documentation and do not need a version bump: npx changeset add --empty

We use semantic versioning, or semver. Read more here: https://semver.org/
In short:

• major if it breaks something.
• minor if it's a functionality that does not break anything.
• patch if it's a bug fix that does not break something.

10. Push and Open a Pull Request
    Read more below about PRs
    Push your branch and open a pull request against the main branch. Describe your changes and reference any related issues.
    • If you have forked, you will create a PR from your branch.

Note: If main has changed significantly you will be required to rebase/merge main into your code to resolve merge conflicts before you can bring your changes into main.

Code Style

For code styling we use husky.

On every commit, after you run npm i your code will be formatted to match the repository.

To help keep your code formatted while you make changes you might consider in vscode setting your default formatter to Prettier (VSCode extension) and in the settings for workspace setting it to format on save.

Reporting Issues

• Report issues directly in GitHub. Using the issue submission tool consider labeling it with a priority to help us gauge if it is a blocker.
• Provide steps to reproduce bugs and relevant logs or screenshots.
• Do NOT post sensitive information such as:
  • IP Addresses
  • Usernames
  • Extended file paths
  • Other such information that could identify systems and/or the versions they are running

Community Standards

• Be respectful and constructive in all communications.

Pull Requests

• Where possible, commits and pull requests should be atomic:
  Keeping commits and PRs to one topic at a time
  • To ensure reviewers can more easily review code revisions and not miss anything
  • Reduces the frequency of merge conflicts
  • Provides separation of concern (for bugs) when only one issue is merged at a time
• You must rebase your branch to main before you submit Pull Requests:
  • [ Terminal ] From your branch run
    1. git fetch origin
    2. git rebase origin/main
  • [ GUI ] In VSCode:
    This can also be done in VSCode using the Version Control menu:
    

Workflow Recommendations

• Use npm link to connect your project or the docs to the local generated groundwork-water
  • See the link script in package.json for details
• Commit Often - Atomic Commits
  • i.e. if you update style of plot, do a commit related to "Update plotxyz style" then move on to next item/commit
• Use VSCode or Similar Featured Editor to provide advanced features, save time, and integrate various utilities:
  • Command Prompt in VSCode : Integrated Terminal
  • Tips & Tricks

Extensions

• TailwindCSS -> Provides you inline tailwind options in your className blocks
• Prettier -> Industry standard for styling, large community, and works in many programming languages
• Better Comments -> Highlight TODO and other type comments
• Code Spell Checker -> Don't let the typos win
• Git Graph -> Adds a graph icon on your "Source Control" line to let you view a visual representation of your git state

Styling / formatting

• Style often and consider [Format on Save for Workspace]()
• Use the Prettier extension mentioned before to format with
  1. Press F1 to open command pallette
  2. Type "format", and then select "Format Document with..."
  3. "Select Prettier"

Working Directories

There are two directories of interest in this repository for Groundwork Water developers

Documentation Website

The /docs directory contains the source code for the documentation website.

To run the docs you can do the following:

npm install
npm run build

cd docs
npm install
npm run dev

This will first install the dependencies for the library then it npm link's the package in the docs.

When you're making frequent changes you might consider importing the components directly from the package. i.e.

import { CWMSPlot } from "../path/to/lib/path/to/component";

This will install the dependencies, and then run the docs in development mode.

NOTE: BE SURE, if you use this method to change the import back to using the library import before committing your changes:

i.e.

import { CWMSPlot } from "@usace-watermanagement/groundwork-water";

If you do not, your changes will be broken in the official NPM release.

groundwork-water npm library

The /lib directory contains the source code for the package itself.

These are the components that would be shared with the community but also within the docs themselves for testing and to showcase the components.

Publishing

Publishing is done automatically via changesets and keys setup in the GitHub secrets. A PR to main with a version bump is sufficient to trigger a publication.

When a PR with a changesets file is merged to the main branch, changesets will automatically aggregate the changes into a new PR that it manages automatically. When desired, library maintainers can trigger a release by merging the changesets-managed PR.

The changesets-managed Version Packages PR is a release PR, not a prerelease. The library changes have already been tested in their original PRs, so the PR validation workflows skip this generated branch. Merging it publishes the package and then builds and deploys the documentation with the newly published package. A failure in that post-merge documentation build is a real release problem and should be fixed rather than ignored or skipped.

The release workflow passes the exact version published by Changesets to the reusable Deploy to GH Pages workflow. Maintainers can also run that workflow manually with an exact package version, or with latest to recover the current release without publishing the package again.

You need only worry about running the command changesets when you are ready to version your changes. Then commit the files the changesets command creates.

We prefer you to run this command and commit prior to making the PR.

Publishing Manually

NOTE: You will first need to be added as a collaborator to the package on NPM.

To publish a new version of the package, run the following command:

npm run publish

This will build the package, and then publish it to NPM.

Questions?

Open an issue or start a discussion if you need help.

Thank you for helping improve Groundwork Water!