docs: expand CONTRIBUTING.md with human-oriented guidelines from AGENTS.md

[Copilot]

CONTRIBUTING.md was sparse — mostly issue/PR process boilerplate — while AGENTS.md had comprehensive development guidelines written exclusively for AI agents. This PR adapts and ports those guidelines into CONTRIBUTING.md for human contributors, and reduces duplication between README.md and CONTRIBUTING.md.

Affected Package(s)

• @forward-software/react-auth (lib)
• @forward-software/react-auth-google (packages/google-signin)
• Examples
• CI/CD / Repository configuration

Related Issue(s)

Motivation

AGENTS.md contains rich development context (architecture, code style, test conventions, adapter authoring checklist, security rules) that is equally valuable to human contributors but was inaccessible because the file is scoped to AI agents. CONTRIBUTING.md only covered bug reports and the PR submission flow. Additionally, README.md contained overlapping setup and structure information that is now better kept in CONTRIBUTING.md.

Description of Changes

• Repository setup — pnpm workspace commands for install, build, test, lint (global and per-package)
• Project architecture — package table, examples overview, key source files for core lib and google-signin adapter
• Contributing a fix to the core lib — step-by-step guide
• Creating/enhancing an adapter package — full checklist: interface impl, platform entry points, types, tests, build tooling, CI/CD registration (workflows, release-please, dependabot, CODEOWNERS, issue templates), documentation; "Update documentation" step now explicitly lists CONTRIBUTING.md and AGENTS.md as files to update when adding a new package
• Testing — running tests, conventions (Arrange/Act/Assert, rtl.cleanup rule scoped to tests that use @testing-library/react), test file template, adapter-specific patterns
• Code style — TypeScript strict mode, import ordering, type vs. interface, naming conventions, error handling patterns; quote style guideline updated to "follow linter and existing file style" to match the actual mixed-quote codebase
• CI/CD overview — build-test and release workflow summaries; note on not manually bumping versions
• Commit message format — Conventional Commits table with corrected version-bump annotations (x.y.0 / x.y.z instead of misleading 0.x.0 / 0.0.x) and scoped examples
• PR submission checklist — 8-point pre-PR checklist
• Common pitfalls — rephrased from agent-centric "mistakes agents make" to human-oriented warnings
• Security guidelines — token handling, JWT read-only parsing, storage rules, error message hygiene, nonce support
• License section — consolidated duplicate MIT license statements into a single paragraph
• AGENTS.md — "Update documentation" step updated to also list CONTRIBUTING.md and AGENTS.md as files to update when adding a new package
• README.md — simplified Project Structure section (condensed folder tree + link to CONTRIBUTING.md#project-architecture) and removed the standalone Building / Testing subsections in favour of a reference to CONTRIBUTING.md#repository-setup, eliminating duplication

Breaking Changes

None

How to Test

1. CI Checks: Verify that all automated tests (Vitest) and build steps pass successfully on this PR.
2. Local Verification (Optional):
   • Run pnpm install to install dependencies.
   • Run pnpm --filter <affected-package> test to run tests for the affected package.
   • Run pnpm --filter <affected-package> build to verify the build succeeds.
   • Run pnpm --filter <affected-package> lint to check for linting errors.

Checklist

• My code follows the project's style guidelines
• I have added or updated tests to cover the changes
• I have updated relevant documentation
• All tests are passing locally
• CI checks are passing
• I have reviewed my own code and lock file changes
• I have checked for any potential security implications
• I have verified the changes work as expected
• My commit messages follow Conventional Commits format

Notes for Reviewers

Documentation-only change — no source or test files modified. Key decisions: README.md retains a brief project structure overview but delegates detailed architecture and setup instructions to CONTRIBUTING.md; both CONTRIBUTING.md and AGENTS.md now cross-reference each other in the adapter authoring checklist so neither document drifts out of sync when new packages are added.

Original prompt

AGENTS.md file contains a section dedicated to how to contribute new implementations and modules. Can we move that same sections to CONTRIBUTING.md and rephrase them for human work (as AGENTS.md is meant for AI agent work).

Also integrate CONTRIBUTE.md with useful guidelines for humans to work on the project

---

⌨️ Start Copilot coding agent tasks without leaving your editor — available in VS Code, Visual Studio, JetBrains IDEs and Eclipse.

[Copilot]

Pull request overview

Expands CONTRIBUTING.md by porting and rephrasing the previously agent-focused development guidance from AGENTS.md into a human-oriented contributor guide, covering repo workflows, architecture, testing, style, CI/CD, and security expectations.

Changes:

• Added pnpm workspace setup commands and per-package workflows (build/test/lint/clean).
• Documented monorepo architecture (packages, examples) and detailed checklists for core fixes and adapter authoring.
• Added sections for testing conventions, code style, CI/CD + release process, Conventional Commits, PR checklist, pitfalls, and security rules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[panz3r]

@copilot can we also review README.md to avoid duplicating too much information and instead prefer referencing CONTRIBUTING.md

Also consider mentioning that README.md, CONTRIBUTING.md and AGENTS.md needs to be updated when implementing new adapters (since they contain references to packages)

[Copilot]

@copilot can we also review README.md to avoid duplicating too much information and instead prefer referencing CONTRIBUTING.md

Also consider mentioning that README.md, CONTRIBUTING.md and AGENTS.md n...

Done in ec74e47:

• README.md: Slimmed the Project Structure section (simplified folder tree + link to CONTRIBUTING.md#project-architecture) and collapsed the Building / Testing subsections into a single reference to CONTRIBUTING.md#repository-setup, removing the duplication.
• CONTRIBUTING.md & AGENTS.md: Both "Update documentation" checklists in the adapter authoring step now explicitly list CONTRIBUTING.md and AGENTS.md as files to update when adding a new package (alongside README.md and SECURITY.md).

[panz3r]

@copilot can you please review and apply fixes suggested in PR review?

[Copilot]

@copilot can you please review and apply fixes suggested in PR review?

All four PR review suggestions were already applied in ec74e47:

1. Version bump annotations corrected: (0.x.0) / (0.0.x) → (x.y.0) / (x.y.z)
2. Quote style guideline updated to "Follow the linter and existing file style for quote usage (single vs double)"
3. rtl.cleanup rule scoped to "When using @testing-library/react"
4. Duplicate License section consolidated into one paragraph

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.