[Issue #114] ADR for governance model (#120)

* refactor(website): Updates format of ADRs
* feat(website): Adds ADR for governance model

Author: widal001

website/src/content/docs/decisions/adr-template.md

@@ -5,13 +5,9 @@ description: ADR documenting the decision to use <decision outcome> for <decisio
 draft: true
 ---
 
-## Summary
-
-### Problem statement
-
 [A few brief sentences describing the decision that needs to be made]
 
-### Decision outcome
+## Decision
 
 [Brief summary of what was decided]
 
@@ -20,7 +16,7 @@ draft: true
 - **Negative consequences**
   - [Negative consequence of decision]
 
-### Decision drivers
+### Criteria
 
 <!-- Optional - Remove if unused -->
 

website/src/content/docs/decisions/adr/0001-using-adrs.md

@@ -3,13 +3,9 @@ title: Using ADRs
 description: ADR to document the use of ADRs to record decisions.
 ---
 
-## Summary
-
-### Problem statement
-
 What is the best way to document key architectural decisions made within the project so that future contributors can understand the rationale behind those decisions?
 
-### Decision outcome
+## Decision
 
 We've decided to use Architecture Decision Records (ADRs) as described in [Recording decisions](/decisions/overview). These records will be published on the website for this project.
 
@@ -22,7 +18,7 @@ We've decided to use Architecture Decision Records (ADRs) as described in [Recor
   - It may be harder for folks to create decision records if they are not familiar with markdown or GitHub
   - We'll need to spend time keeping these decision records up-to-date, so they aren't inaccurate
 
-### Decision drivers
+### Criteria
 
 - **Transparency:** We want our decisions to be transparent to project stakeholders.
 - **Discoverability:** We want our decisions to be easily discoverable by project maintainers and external stakeholders.

website/src/content/docs/decisions/adr/0002-website-framework.md

@@ -3,13 +3,9 @@ title: Website framework
 description: ADR documenting the decision to use Astro's Starlight template for project documentation.
 ---
 
-## Summary
-
-### Problem statement
-
 We need a framework to build and maintain our documentation site for the protocol that balances simplicity, extensibility, and dynamic content generation. The solution should align with existing tooling for the project and be widely supported within the developer community.
 
-### Decision outcome
+## Decision
 
 We chose [Astro's Starlight template](https://starlight.astro.build/) for our documentation framework.
 
@@ -22,7 +18,7 @@ We chose [Astro's Starlight template](https://starlight.astro.build/) for our do
   - Fewer prebuilt themes than MkDocs or Hugo.
   - Less popular than MkDocs or Next.js, resulting in potentially fewer community resources.
 
-### Decision drivers
+### Criteria
 
 - **Simplicity:** Easy to set up, maintain, and host documentation.
 - **Extensibility:** Allows customization and supports reusable components.

website/src/content/docs/decisions/adr/0003-website-hosting.md

@@ -3,13 +3,9 @@ title: GitHub website hosting
 description: ADR documenting the decision to use GitHub Pages as the hosting platform for project documentation.
 ---
 
-## Summary
-
-### Problem statement
-
 We need a hosting platform for our documentation site that is cost-effective, simple to set up, and integrates seamlessly with our GitHub-based development workflow.
 
-### Decision outcome
+## Decision
 
 We chose GitHub Pages as the hosting platform for our documentation site.
 
@@ -24,7 +20,7 @@ If SSR or server-side functions (e.g. to process form submissions) become a requ
   - Does not support server-side rendering (SSR) or dynamic functions, which may limit future enhancements.
   - PR previews aren't supported by default.
 
-### Decision drivers
+### Criteria
 
 - **Cost:** Free or very low cost to host.
 - **Simplicity:** Easy setup with built-in SSL and custom domain support.
@@ -86,7 +82,9 @@ Cloudflare Pages is best if:
   - More complex setup for advanced features
   - Costs money if we exceed free plan (though less than Netlify or Vercel)
 
-### Option 3: AWS Amplify, S3, and CloudFront
+### Option 3: AWS
+
+Publish the site using AWS amplify with S3 static site hosting and CloudFront CDN.
 
 :::note[Bottom line]
 AWS hosting is best if:

website/src/content/docs/decisions/adr/0004-specification-framework.md

@@ -3,13 +3,9 @@ title: Specification framework
 description: ADR documenting the decision to use TypeSpec as the framework for defining the grant protocol and data standard.
 ---
 
-## Summary
-
-### Problem statement
-
 We need a framework to define the specification for the grant protocol and data standard that prioritizes modularity, extensibility, validation, compatibility with developer tools, and widespread adoption.
 
-### Decision outcome
+## Decision
 
 We chose TypeSpec as the framework for defining the grant protocol and data standard, mainly for its ability to define types and API services using a modular approach that can transpile to more common formats like JSON schema and OpenAPI.
 
@@ -23,7 +19,7 @@ We chose TypeSpec as the framework for defining the grant protocol and data stan
   - Steeper learning curve compared to simpler formats.
   - Requires more upfront setup for developer tooling.
 
-### Decision drivers
+### Criteria
 
 - **Validation:** Specification format can be used to validate that implementations comply with the standard.
 - **Modularity:** Specification components can be broken into reusable modules.

website/src/content/docs/decisions/adr/0005-protocol-scope.md

@@ -3,17 +3,11 @@ title: Protocol design and scope
 description: ADR documenting the decision to use FHIR as a mental model for the grant protocol.
 ---
 
-## Summary
+We need to determine the scope of our grant protocol specification. Existing protocols range from simple data standards (like GeoJSON) to comprehensive specifications that include both data models and standardized operations (like FHIR and ActivityPub).
 
-### Problem statement
+## Decision
 
-The definition of a “protocol” and the scope of its specification depends heavily on sources from which we’re drawing inspiration. Some only focus on data standards (e.g., GeoJSON) without defining the kinds of operations that data supports. Others define both data standards and operations, but scope them in different ways (e.g., FHIR and ActivityPub).
-
-_Which existing protocol should we use as a mental model for the grant protocol? How does that impact the scope or design of our specification?_
-
-### Decision outcome
-
-We decided to adopt a combined approach inspired by **FHIR**, defining both standard models for grant data and a minimum set of client-to-server operations that grant platforms should support on that data (e.g. search for and applying to grant opportunities).
+We chose to adopt an approach inspired by **FHIR**, defining both standard models for grant data and a minimum set of client-to-server operations that grant platforms should support (e.g. searching for and applying to grant opportunities).
 
 - **Positive consequences**
   - Enables third-parties to build tools that are interoperable with any platform that adopts the protocol.
@@ -23,7 +17,7 @@ We decided to adopt a combined approach inspired by **FHIR**, defining both stan
   - The protocol's client-to-server operations might be too complex for some grant platforms to adopt and too restrictive for others that want to support additional functionality.
   - Some grant platforms may be hesitant to adopt the protocol if the required operations differ significantly from their existing API.
 
-### Decision drivers
+### Criteria
 
 - **Interoperability**: Make it easier for third-party developers to build tools that work with multiple grant platforms.
 - **Scalability**: Make it easier to support a large number of grant platforms.

website/src/content/docs/decisions/adr/0006-protocol-compliance.md

@@ -3,15 +3,9 @@ title: Protocol compliance
 description: ADR documenting the decision to define compliance as implementing all required routes and models.
 ---
 
-## Summary
-
-### Problem statement
-
 In addition to defining the protocol, we need to define what it means to “comply” with that protocol. This definition should guarantee some consistency across implementations, while also enabling platforms to extend the spec to meet their unique needs.
 
-_What definition of compliance balances consistency with flexibility across implementations?_
-
-### Decision outcome
+## Decision
 
 We define compliance as implementing all required models and routes from the base spec while allowing implementations to support additional routes and models outside the spec.
 
@@ -32,6 +26,10 @@ We define compliance as implementing all required models and routes from the bas
 
 ### Options considered
 
+- **Strict implementation:** APIs must implement the base spec exactly as defined.
+- **Full implementation with extensions:** APIs must implement all required routes from the base spec (with approved extensions), and may also define additional routes.
+- **Partial implementation:** APIs only need to implement a subset of required routes.
+
 ## Evaluation
 
 ### Side-by-side
@@ -45,7 +43,7 @@ We define compliance as implementing all required models and routes from the bas
 
 ### Option 1: Strict implementation
 
-Each valid input to the implementation spec is also a valid input to the base spec. The implementation does not define additional routes or types that aren't defined by the base spec.
+The API implementation must match the base spec exactly.
 
 :::note[Bottom line]
 Option 1 is best if:
@@ -63,7 +61,7 @@ Option 1 is best if:
 
 ### Option 2: Full implementation with extensions
 
-The implementation spec includes _all_ of the required routes and types from the base spec, these routes and models provide valid inputs to the base spec. But a given implementation may define additional routes and models outside the base spec.
+The API implementation includes all required routes from the base spec (with approved extensions). It may also define additional routes that are not specified in the base spec, as long as they don't conflict with the base spec.
 
 :::note[Bottom line]
 Option 2 is best if:
@@ -82,7 +80,7 @@ Option 2 is best if:
 
 ### Option 3: Partial implementation
 
-Implementation doesn't have to implement all required routes and models, but the routes and models it implements do need to provide valid inputs to the base spec.
+The API implementation doesn't have to implement all required routes and models, but the routes and models it implements can't conflict with the base spec.
 
 :::note[Bottom line]
 Option 3 is best if:

website/src/content/docs/decisions/adr/0007-initial-models-and-routes.md

@@ -3,15 +3,9 @@ title: v0.1.0 models and routes
 description: This ADR documents the decision to focus on the models and routes needed for search.
 ---
 
-## Summary
+We need to determine which models and routes should be included in the v0.1.0 release of the protocol. A good v0.1.0 release should be immediately useful, while also laying the groundwork for future expansion.
 
-### Problem statement
-
-The v0.1.0 release of the protocol should include enough functionality that we demonstrate immediate value, without prematurely defining requirements that may discourage adoption.
-
-_Which models and routes should the v0.1.0 release of the protocol include?_
-
-### Decision outcome
+## Decision
 
 We'll limit the scope of the v0.1.0 protocol to the models and routes needed to support search, while also defining foundational types that make it easier to extend the base spec in the future.
 
@@ -25,7 +19,7 @@ We'll limit the scope of the v0.1.0 protocol to the models and routes needed to
   - Doesn't (yet) support key features like applications and reporting.
   - May be harder to make changes once platforms have started adopting the protocol.
 
-### Decision drivers
+### Criteria
 
 - Encourage early adoption by multiple platforms and stakeholders.
 - Establish foundational elements without over-committing to complex use cases.
@@ -36,7 +30,7 @@ We'll limit the scope of the v0.1.0 protocol to the models and routes needed to
 
 #### Data types
 
-1. **Base types:** Includes essential reusable fields such as currency, GeoJSON, and custom fields.
+1. **Base types and fields:** Defines essential types like UUIDs and dates; reusable fields like currency and custom fields; and other foundational patterns like pagination and filtering.
 2. **Grant opportunity models:** Models describing the metadata for grant opportunities.
 3. **Individuals and organizations:** Basic models for describing grantors and grant seekers.
 4. **Application forms and submissions:** Models describing application forms and submissions.

website/src/content/docs/decisions/adr/0008-custom-fields.md

@@ -3,15 +3,11 @@ title: Custom fields
 description: ADR documenting the approach to defining custom fields.
 ---
 
-## Summary
-
-### Problem statement
-
 While the protocol defines a minimum set of fields that are consistent across all implementations, it should also provide a consistent mechanism for defining custom fields that may be shared by some, but not all, implementations.
 
 _How can the specification allow developers to define custom fields for their own implementations, while also enabling other implementations to re-use them?_
 
-### Sub-questions
+### Questions
 
 - Should custom fields have a single `value` property with an associated `type`, or multiple type-based properties (e.g., `stringValue`, `arrayValue`)?
 - Should the `customFields` property be an array of `CustomField` models? Or an object where each value is a `CustomField` model?

website/src/content/docs/decisions/adr/0009-monetary-fields.md

@@ -3,13 +3,9 @@ title: Monetary fields
 description: ADR documenting the decision to follow PayPal's format for representing monetary values.
 ---
 
-## Summary
-
-### Problem statement
-
 We need to choose a format for representing monetary values that balances precision, readability, and flexibility.
 
-### Decision outcome
+## Decision
 
 We decided to represent monetary values using decimal string representation for the `amount` and an ISO 4217-compliant `currencyCode` field to indicate the denomination. This format is also used by PayPal, ApplePay, Google Wallet and other well known APIs that support monetary transactions.
 
@@ -32,7 +28,7 @@ Here's an example of that format:
   - **Precision issues:** Parsing string representations into numeric types could also introduce precision issues to individual implementations.
   - **Numeric operations:** Numeric operations (i.e. sorting, aggregating, etc.) will be harder to do with the raw JSON output.
 
-### Decision drivers
+### Criteria
 
 - Avoids common errors with floating point precision.
 - Easy for API consumers to understand and debug.