USACE · krowvin · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,16 @@
+## Summary
+
+- Describe the change.
+- Link the related issue if there is one.
+
+## Checklist
+
+- [ ] I ran `npm run lint`
+- [ ] I ran `npm test` or documented why tests were not needed
+- [ ] I updated docs/examples if the component API or behavior changed
+- [ ] I added screenshots for UI changes when useful
+- [ ] I applied exactly one version label: `patch-bump`, `minor-bump`, or `major-bump`
+
+## Release impact
+
+- Explain why the selected version bump label is correct.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,66 @@
+# Contributing to Groundwork
+
+Groundwork is a shared React component library for USACE applications. Keep changes small, well-scoped, and documented so maintainers can review and release them predictably.
+
+## Development setup
+
+Groundwork's GitHub Actions workflows run on Node 20. Use the same version locally when possible.
+
+```bash
+npm install
+npm run dev
+npm test
+npm run lint
+```
+
+## Coding standards
+
+- Use Prettier formatting. A Husky pre-commit hook runs `lint-staged`, which applies Prettier to staged `js`, `jsx`, `json`, `css`, and `md` files.
+- Run `npm run lint` before opening a pull request. ESLint is configured for the React codebase and should stay clean.
+- Add or update tests when behavior changes. `lib/gw-merge.test.js` shows the existing Vitest setup.
+- Update the documentation app in `src/app-pages/documentation` when a component API, behavior, or usage pattern changes.
+- Edit source files in `src` and `lib`. Do not hand-edit generated output in `dist` or the built docs output in `docs`.
+
+## Branch naming
+
+Branch from issue so everything is connected. This means every change starts with an issue rather than just an "idea".
+
+## Pull requests
+
+- Link the issue or describe the problem the PR solves (See Branch Naming above)
+- Keep each PR focused on one change set. Separate refactors from behavior changes when possible.
+- Include screenshots or short screen recordings for visible UI changes.
+- Call out any accessibility, API, or migration impact in the PR description.
+- Request review from a Groundwork maintainer before merging.
+
+## Reviews
+
+Reviewers should be able to answer three questions quickly:
+
+1. Is the change scoped correctly for Groundwork?
+2. Are tests and docs updated for the new behavior?
+3. Is the selected version bump correct? (Major, Minor, Patch)
+
+Contributors should address review comments with follow-up commits unless a maintainer asks for a different workflow.
+
+## Versioning and releases
+
+Groundwork uses semantic versioning and enforces version bump labels on pull requests to `main`.
+
+- `patch-bump`: bug fixes, docs-only changes, maintenance work, and backward-compatible internal cleanup
+- `minor-bump`: new backward-compatible components, props, or behavior
+- `major-bump`: breaking API changes, removals, or behavior that requires consumer updates
+
+Current repository automation expects exactly one of these labels on every PR to `main`:
+
+- `patch-bump`
+- `minor-bump`
+- `major-bump`
+
+After a PR is merged into `main`, the `pr-close.yml` workflow bumps the package version and pushes the tag. Publishing to npm happens when a GitHub Release is published, which triggers `.github/workflows/publish.yml`.
+
+## Commit guidance
+
+- Prefer small commits with clear messages that describe the intent of the change.
+- Avoid mixing formatting-only changes with feature or bug-fix commits unless the formatter was required for touched files.
+- Do not rewrite shared branch history unless the maintainers ask for it.
diff --git a/README.md b/README.md
@@ -10,6 +10,8 @@ The library is available on NPM at `@usace/groundwork` - watch the version numbe
 
 We welcome contributions from USACE developers and want to make this a community project.
 
+Contribution standards, PR expectations, and release/versioning guidance are documented in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Friends of Groundwork
 
 ### USACE WM Components

diff --git a/src/app-bundles/routes-bundle.js b/src/app-bundles/routes-bundle.js
@@ -46,6 +46,7 @@ import QuickStartGuide from "../app-pages/documentation/getting-started/quick-st
 import AddingTailwind from "../app-pages/documentation/getting-started/adding-tailwind";
 import ClientSideRouting from "../app-pages/documentation/getting-started/client-side-routing";
 import PackageMaintenance from "../app-pages/documentation/getting-started/package-maintenance";
+import ContributionGuide from "../app-pages/documentation/getting-started/contribution-guide";
 import LinkProviderDocs from "../app-pages/documentation/navigation/link-provider";
 import DividerDocs from "../app-pages/documentation/display/divider";
 import ModalDocs from "../app-pages/documentation/display/modal";
@@ -60,6 +61,7 @@ export default createRouteBundle(
     "/docs/adding-tailwind": AddingTailwind,
     "/docs/client-side-routing": ClientSideRouting,
     "/docs/package-maintenance": PackageMaintenance,
+    "/docs/contribution-guide": ContributionGuide,
     "/docs/app-shell": AppShell,
     "/docs/app-shell/site-wrapper": SiteWrapperDocs,
     "/docs/app-shell/search": SearchDocs,

diff --git a/src/app-pages/documentation/getting-started/contribution-guide.jsx b/src/app-pages/documentation/getting-started/contribution-guide.jsx
@@ -0,0 +1,168 @@
+import { Code, H3, Text, TextLink, UsaceBox } from "../../../../lib";
+import DocsPage from "../_docs-page";
+
+const pageBreadcrumbs = [
+  {
+    text: "Documentation",
+    href: "/#/docs",
+  },
+  {
+    text: "Getting Started",
+    href: "/#/docs",
+  },
+  {
+    text: "Contribution Guide",
+    href: "/#/docs/contribution-guide",
+  },
+];
+
+function P({ children }) {
+  return <Text className="gw-pt-3 gw-pb-3">{children}</Text>;
+}
+
+function ContributionGuide() {
+  return (
+    <DocsPage breadcrumbs={pageBreadcrumbs}>
+      <UsaceBox title="Contribution Guide">
+        <div className="gw-pb-6">
+          <P>
+            Groundwork is a shared React component library for USACE
+            applications. Contributions should stay focused, keep the component
+            library stable for downstream consumers, and include the docs or
+            tests needed to support the change.
+          </P>
+
+          <H3 className="gw-mt-6">Development setup</H3>
+          <P>
+            Groundwork&apos;s GitHub Actions workflows run on Node 20, so use
+            the same version locally when possible.
+          </P>
+          <Code className="!gw-font-bold">terminal</Code>
+          <pre className="gw-mt-3 gw-overflow-x-auto gw-rounded gw-bg-slate-900 gw-p-4 gw-text-sm gw-text-white">
+            <code>{`npm install
+npm run dev
+npm test
+npm run lint`}</code>
+          </pre>
+
+          <H3 className="gw-mt-6">Coding standards</H3>
+          <ul className="gw-list-disc gw-pl-6 gw-pt-3 gw-pb-3">
+            <li>
+              Use Prettier formatting. A Husky pre-commit hook runs{" "}
+              <Code>lint-staged</Code> on staged <Code>js</Code>,{" "}
+              <Code>jsx</Code>, <Code>json</Code>, <Code>css</Code>, and{" "}
+              <Code>md</Code> files.
+            </li>
+            <li>
+              Run <Code>npm run lint</Code> before opening a pull request.
+            </li>
+            <li>
+              Add or update tests when behavior changes. Groundwork uses Vitest
+              for the current test suite.
+            </li>
+            <li>
+              Update the documentation pages when a component API, usage
+              pattern, or behavior changes.
+            </li>
+            <li>
+              Edit source in <Code>src</Code> and <Code>lib</Code>. Do not
+              hand-edit built output in <Code>dist</Code> or <Code>docs</Code>.
+              These are generated from the source files and will be overwritten
+              by the build process.
+            </li>
+          </ul>
+
+          <H3 className="gw-mt-6">Routing links in components</H3>
+          <P>
+            When adding links inside Groundwork components, prefer the exported{" "}
+            <Code>{`<Link />`}</Code> component instead of hard-coding raw{" "}
+            <Code>{`<a>`}</Code> elements where LinkProvider support is
+            expected. That allows applications using{" "}
+            <Code>{`<LinkProvider />`}</Code> to swap in their routing
+            library&apos;s link component correctly.
+          </P>
+          <P>
+            See the{" "}
+            <TextLink href="/#/docs/navigation/link-provider">
+              Link Provider documentation
+            </TextLink>{" "}
+            for the routing integration details and expected behavior.
+          </P>
+
+          <H3 className="gw-mt-6">Branch naming</H3>
+          <P>
+            Use short-lived topic branches for each change. Prefer patterns like{" "}
+            <Code>feature/issue-&lt;number&gt;-short-description</Code>,{" "}
+            <Code>fix/issue-&lt;number&gt;-short-description</Code>,{" "}
+            <Code>docs/issue-&lt;number&gt;-short-description</Code>, or{" "}
+            <Code>chore/issue-&lt;number&gt;-short-description</Code>.
+          </P>
+          <P>
+            If there is no issue number yet, omit that segment and keep the
+            description concise.
+          </P>
+
+          <H3 className="gw-mt-6">Pull requests and reviews</H3>
+          <ul className="gw-list-disc gw-pl-6 gw-pt-3 gw-pb-3">
+            <li>
+              Link the issue or describe the problem the pull request solves.
+            </li>
+            <li>Keep each pull request focused on one change set.</li>
+            <li>Include screenshots for visible UI changes when useful.</li>
+            <li>
+              Call out accessibility, API, or migration impact in the pull
+              request description.
+            </li>
+            <li>Request review from a Groundwork maintainer before merging.</li>
+          </ul>
+          <P>
+            Reviewers should be able to confirm the scope is appropriate, the
+            docs and tests match the change, and the selected version bump is
+            correct.
+          </P>
+
+          <H3 className="gw-mt-6">Versioning and releases</H3>
+          <P>
+            Groundwork uses semantic versioning and requires exactly one version
+            label on every pull request to <Code>main</Code>.
+          </P>
+          <ul className="gw-list-disc gw-pl-6 gw-pt-3 gw-pb-3">
+            <li>
+              <Code>patch-bump</Code>: bug fixes, docs-only changes, and
+              backward-compatible maintenance work
+            </li>
+            <li>
+              <Code>minor-bump</Code>: new backward-compatible components,
+              props, or behavior
+            </li>
+            <li>
+              <Code>major-bump</Code>: breaking API changes, removals, or
+              behavior that requires consumer updates
+            </li>
+          </ul>
+          <P>
+            After a pull request is merged, repository automation bumps the
+            package version and pushes the tag. Publishing to npm happens when a
+            GitHub Release is published.
+          </P>
+
+          <H3 className="gw-mt-6">Reference</H3>
+          <P>
+            The canonical repo guidance also lives in{" "}
+            <TextLink
+              href="https://github.com/USACE/groundwork/blob/main/CONTRIBUTING.md"
+              target="_blank"
+              rel="noreferrer"
+            >
+              CONTRIBUTING.md on GitHub
+            </TextLink>
+            .
+          </P>
+        </div>
+      </UsaceBox>
+    </DocsPage>
+  );
+}
+
+export default ContributionGuide;
+export { ContributionGuide };
diff --git a/src/app-pages/documentation/index.jsx b/src/app-pages/documentation/index.jsx
@@ -75,6 +75,16 @@ function Docs() {
           Make sure to import style.css from Groundwork into your top-level
           component (i.e. App.jsx), then go build stuff with the components
         </Text>
+
+        <H4 className="gw-mt-6">Contributing</H4>
+        <Text className="gw-mt-3">
+          If you are planning to contribute to Groundwork, review the{" "}
+          <a className="gw-underline" href="/docs/contribution-guide">
+            contribution guide
+          </a>{" "}
+          for branch naming, pull request expectations, and version bump
+          labeling.
+        </Text>
       </UsaceBox>
     </DocsPage>
   );

diff --git a/src/app-pages/home.jsx b/src/app-pages/home.jsx
@@ -59,10 +59,18 @@ function Home() {
             >
               <Text>
                 Contributions are welcome! Please see the{" "}
-                <TextLink href="https://github.com/USACE/groundwork">
-                  GitHub Repository
+                <TextLink href="/#/docs/contribution-guide">
+                  contribution guide
                 </TextLink>{" "}
-                for more information.
+                for workflow and review expectations. The{" "}
+                <TextLink
+                  href="https://github.com/USACE/groundwork"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  GitHub repository
+                </TextLink>{" "}
+                has the source and issue tracker.
               </Text>
             </UsaceBox>
           </div>

diff --git a/src/nav-links.js b/src/nav-links.js
@@ -24,6 +24,11 @@ export default [
         text: "Package Maintenance",
         href: "/#/docs/package-maintenance",
       },
+      {
+        id: "contribution-guide",
+        text: "Contribution Guide",
+        href: "/#/docs/contribution-guide",
+      },
     ],
   },
   {