development-workflow

name

development-workflow

description

ReactiveProperty repository development policy. Use whenever you implement a feature or bug fix, change library or test code under Source/ or Test/, make a design or architecture decision, or write documentation in this repo. Enforces strict Test-Driven Development (Red -> Green -> Refactor) with MSTest and `dotnet test ReactiveProperty.slnx`, requires recording design decisions as ADRs under dev-docs/adr/, and defines the documentation split: docs/ is user-facing (plain Markdown browsed on GitHub) while dev-docs/ holds implementer/contributor documentation. Triggers include "implement", "add feature", "fix bug", "TDD", "red green refactor", "design decision", "architecture", "ADR", "where do docs go", and "contributor docs".

Development Workflow (ReactiveProperty)

The required development workflow and documentation policy for this repository.

When to Use

• Implementing any feature or bug fix in Source/ or Test/.
• Making a design or architecture decision (public API shape, threading model, new package, dependency, breaking change).
• Deciding where a piece of documentation belongs.

When Not to Use

• Pure release/versioning mechanics (see AGENTS.md and the build/publish workflow).
• One-off exploration or read-only investigation with no code change.

---

1. TDD is mandatory — Red → Green → Refactor

Every code change to Source/ must be driven by a failing test first. Follow the cycle strictly and do not skip steps:

1. Red — Write the smallest test that expresses the desired behavior, then run it and watch it fail. The failure must be for the right reason (asserting the new behavior, not a compile error you didn't expect).

   dotnet test ReactiveProperty.slnx
   

   Narrow the loop while iterating, e.g. a single project or filter:

   dotnet test Test/ReactiveProperty.NETStandard.Tests/ReactiveProperty.NETStandard.Tests.csproj --filter "FullyQualifiedName~YourNewTest"
   

2. Green — Write the minimum production code to make the test pass. Re-run the tests and confirm they are green. Don't add unrequested functionality.
3. Refactor — With tests green, clean up production and test code (naming, duplication, structure). Re-run tests after refactoring; they must stay green. Behavior must not change.

Rules:

• Never write production code without a failing test that requires it.
• Keep each Red→Green→Refactor cycle small and focused on one behavior.
• A change is not "done" until dotnet test ReactiveProperty.slnx passes on Windows (WPF/UWP projects require Windows).

Test conventions (this repo)

• Framework: MSTest (MSTest.TestAdapter / MSTest.TestFramework).
• Helpers available: Moq, Microsoft.Reactive.Testing (TestScheduler for time-based Rx), the bundled ChainingAssertion (actual.Is(expected) fluent assertions); Blazor tests use bunit.
• Put tests in the matching Test/* project; the core test project uses namespace ReactiveProperty.Tests.
• Keep new Source/ code compatible with netstandard2.0 / net472 (lowest TFMs).

See the writing-mstest-tests and run-tests skills for MSTest authoring details and filter/runner syntax.

---

2. Record design decisions as ADRs

Going forward, every non-trivial design / architecture decision is recorded as an Architecture Decision Record (ADR).

Write an ADR when you:

• add or remove a public API surface, or change its semantics;
• add a new package/project or a new external dependency;
• change threading/scheduling, validation, or serialization behavior;
• make a breaking change or deprecate something;
• choose between competing implementation approaches with long-term impact.

How:

• ADRs live in dev-docs/adr/, one file per decision.
• Copy dev-docs/adr/template.md, name it NNNN-short-title.md with the next zero-padded number (e.g. 0002-...), and fill in Status, Context, Decision, Consequences.
• New ADRs start as Status: Proposed; mark Accepted once agreed. Don't edit accepted ADRs to reverse a decision — add a new ADR that supersedes the old one and update both Status lines.
• Add the new ADR to the index in dev-docs/adr/README.md.

Trivial, reversible choices (local refactors, naming) do not need an ADR.

---

3. Documentation split: docs/ vs dev-docs/

• docs/ = user-facing documentation, plain Markdown browsed directly on GitHub (no site generator). Write here for library consumers: getting-started, API usage, samples. Available in English and Japanese (*-ja). Keep links relative (.md).
• dev-docs/ = implementer/contributor-facing documentation, not published. Write here for people working on ReactiveProperty: architecture notes, internal design, contributor workflow, and ADRs (dev-docs/adr/).

When you add documentation, pick the audience first:

• "How does a consumer use this feature?" → docs/.
• "How/why is this implemented, or how do I contribute?" → dev-docs/.

---

Checklist before finishing a change

• Behavior was driven by a failing test first (Red), then made to pass (Green), then refactored.
• dotnet test ReactiveProperty.slnx passes.
• New Source/ code stays compatible with netstandard2.0 / net472.
• Any design/architecture decision is captured as an ADR in dev-docs/adr/ and indexed.
• New docs placed by audience (docs/ for users, dev-docs/ for implementers).