diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d4fb71e --- /dev/null +++ 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 new file mode 100644 index 0000000..2114949 --- /dev/null +++ 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 index e6d5fed..445baa4 100644 --- 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 index 8984767..7a43c9d 100644 --- 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 new file mode 100644 index 0000000..cca5608 --- /dev/null +++ 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 {children}; +} + +function ContributionGuide() { + return ( + + +
+

+ 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. +

+ +

Development setup

+

+ Groundwork's GitHub Actions workflows run on Node 20, so use + the same version locally when possible. +

+ terminal + 
+            {`npm install
+npm run dev
+npm test
+npm run lint`}
+
+ +

Coding standards

+
    +
  • + Use Prettier formatting. A Husky pre-commit hook runs{" "} + lint-staged on staged js,{" "} + jsx, json, css, and{" "} + md files. +
    • +
  • + Run npm run lint before opening a pull request. +
    • +
  • + Add or update tests when behavior changes. Groundwork uses Vitest + for the current test suite. +
    • +
  • + Update the documentation pages when a component API, usage + pattern, or behavior changes. +
    • +
  • + Edit source in src and lib. Do not + hand-edit built output in dist or docs. + These are generated from the source files and will be overwritten + by the build process. +
    • +
+ +

Routing links in components

+

+ When adding links inside Groundwork components, prefer the exported{" "} + {``} component instead of hard-coding raw{" "} + {``} elements where LinkProvider support is + expected. That allows applications using{" "} + {``} to swap in their routing + library's link component correctly. +

+

+ See the{" "} + + Link Provider documentation + {" "} + for the routing integration details and expected behavior. +

+ +

Branch naming

+

+ Use short-lived topic branches for each change. Prefer patterns like{" "} + feature/issue-<number>-short-description,{" "} + fix/issue-<number>-short-description,{" "} + docs/issue-<number>-short-description, or{" "} + chore/issue-<number>-short-description. +

+

+ If there is no issue number yet, omit that segment and keep the + description concise. +

+ +

Pull requests and reviews

+
    +
  • + Link the issue or describe the problem the pull request solves. +
    • +
  • Keep each pull request focused on one change set.
    • +
  • Include screenshots for visible UI changes when useful.
    • +
  • + Call out accessibility, API, or migration impact in the pull + request description. +
    • +
  • Request review from a Groundwork maintainer before merging.
    • +
+

+ Reviewers should be able to confirm the scope is appropriate, the + docs and tests match the change, and the selected version bump is + correct. +

+ +

Versioning and releases

+

+ Groundwork uses semantic versioning and requires exactly one version + label on every pull request to main. +

+
    +
  • + patch-bump: bug fixes, docs-only changes, and + backward-compatible maintenance work +
    • +
  • + minor-bump: new backward-compatible components, + props, or behavior +
    • +
  • + major-bump: breaking API changes, removals, or + behavior that requires consumer updates +
    • +
+

+ 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. +

+ +

Reference

+

+ The canonical repo guidance also lives in{" "} + + CONTRIBUTING.md on GitHub + + . +

+
+ + + ); +} + +export default ContributionGuide; +export { ContributionGuide }; diff --git a/src/app-pages/documentation/index.jsx b/src/app-pages/documentation/index.jsx index 9e918f1..516f9e2 100644 --- 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 + +

Contributing

+ + If you are planning to contribute to Groundwork, review the{" "} + + contribution guide + {" "} + for branch naming, pull request expectations, and version bump + labeling. + ); diff --git a/src/app-pages/home.jsx b/src/app-pages/home.jsx index 80fad75..9624198 100644 --- a/src/app-pages/home.jsx +++ b/src/app-pages/home.jsx @@ -59,10 +59,18 @@ function Home() { > Contributions are welcome! Please see the{" "} - - GitHub Repository + + contribution guide {" "} - for more information. + for workflow and review expectations. The{" "} + + GitHub repository + {" "} + has the source and issue tracker. diff --git a/src/nav-links.js b/src/nav-links.js index b9163bd..8698200 100644 --- 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", + }, ], }, {