83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# Contributing to CascadingDev
|
|
|
|
First off, thank you for considering contributing! It's people like you that make CascadingDev such a great tool.
|
|
|
|
This document provides a guide for contributors on how to participate in the development process, particularly around the voting and automated status promotion system.
|
|
|
|
## The Voting System
|
|
|
|
The core of the collaborative process in CascadingDev revolves around a simple voting system within discussion files. This system is used to gauge consensus and drive the automated workflow.
|
|
|
|
### Vote Types
|
|
|
|
There are three types of votes you can cast:
|
|
|
|
* `VOTE: READY`: You are satisfied with the current state of the discussion and believe it's ready to move to the next stage.
|
|
* `VOTE: CHANGES`: You believe changes are needed before the discussion can proceed. You should accompany this vote with comments outlining the required changes.
|
|
* `VOTE: REJECT`: You believe the proposal should be rejected. This is a strong vote that can halt a discussion's progress.
|
|
|
|
### How to Vote
|
|
|
|
To cast a vote, add your name and comment to the relevant discussion file (e.g., `feature.discussion.md`). The format is as follows:
|
|
|
|
```markdown
|
|
Name: Your Name
|
|
|
|
Your comment about the proposal.
|
|
|
|
VOTE: READY
|
|
```
|
|
|
|
The system only considers the **latest** vote from each participant.
|
|
|
|
## Automated Status Promotion
|
|
|
|
CascadingDev uses the votes from participants to automatically promote the status of a discussion. This is controlled by a `promotion_rule` defined in the YAML front matter of the discussion file.
|
|
|
|
### The `promotion_rule`
|
|
|
|
Here is an example of a `promotion_rule` in a `feature.discussion.md` file:
|
|
|
|
```yaml
|
|
---
|
|
type: feature-discussion
|
|
stage: feature
|
|
status: OPEN
|
|
promotion_rule:
|
|
allow_agent_votes: false
|
|
ready_min_eligible_votes: 2
|
|
reject_min_eligible_votes: 1
|
|
ready_status: "READY_FOR_DESIGN"
|
|
reject_status: "FEATURE_REJECTED"
|
|
---
|
|
|
|
Name: Alice
|
|
I think this is a great idea.
|
|
VOTE: READY
|
|
|
|
---
|
|
|
|
Name: Bob
|
|
I agree, let's move forward.
|
|
VOTE: READY
|
|
```
|
|
|
|
### Parameters
|
|
|
|
* `allow_agent_votes` (boolean, optional): If `true`, votes from participants with names starting with `AI_` will be counted. Defaults to `false`.
|
|
* `ready_min_eligible_votes` (integer | "all", optional): The number of `READY` votes required to promote the status. If set to `"all"`, all eligible voters must vote `READY`. Defaults to `2`.
|
|
* `reject_min_eligible_votes` (integer | "all", optional): The number of `REJECT` votes required to reject the discussion. Defaults to `1`.
|
|
* `ready_status` (string, optional): The status to set when the `ready` threshold is met. This is typically the next stage in the lifecycle (e.g., `READY_FOR_DESIGN`).
|
|
* `reject_status` (string, optional): The status to set when the `reject` threshold is met (e.g., `FEATURE_REJECTED`).
|
|
|
|
### Lifecycle of a Discussion
|
|
|
|
The automated status promotion creates a lifecycle for discussions:
|
|
|
|
1. A **feature discussion** starts with `status: OPEN`. When enough `READY` votes are cast, its status is promoted to `READY_FOR_DESIGN`.
|
|
2. This triggers the creation of a **design discussion**.
|
|
3. The design discussion goes through the same voting process. When it's ready, its status is promoted to `READY_FOR_IMPLEMENTATION`.
|
|
4. This, in turn, can trigger the AI to start writing code.
|
|
|
|
This automated, vote-driven workflow is at the heart of what makes CascadingDev a powerful tool for collaborative, AI-assisted development.
|