govctl 0.17.0

Project governance CLI for RFC, ADR, and Work Item management
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

use clap::Subcommand;

use crate::model::RfcPhase;
use crate::{
    CommonDeprecateArgs, CommonEditArgs, CommonGetArgs, CommonListArgs, CommonRenderArgs,
    CommonShowArgs, CommonSupersedeArgs, FinalizeStatus,
};

/// RFC commands (resource-first structure)
#[derive(Subcommand, Clone, Debug)]
pub(crate) enum RfcCommand {
    /// List RFCs
    #[command(after_help = "\
FILTERS:
    Filter may be an RFC status, phase, or ID/title substring.

EXAMPLES:
    govctl rfc list
    govctl rfc list draft
    govctl rfc list impl -n 5
    govctl rfc list RFC-0002 -o json
")]
    List(CommonListArgs),
    /// Get RFC metadata or specific field
    #[command(after_help = "\
VALID FIELDS:
    - title, version, status, phase, owners, refs, changelog

EXAMPLES:
    govctl rfc get RFC-0001
    govctl rfc get RFC-0001 title
    govctl rfc get RFC-0001 refs
")]
    Get(CommonGetArgs),
    /// Show rendered RFC content
    #[command(after_help = "\
EXAMPLES:
    govctl rfc show RFC-0001
    govctl rfc show RFC-0001 --history
    govctl rfc show RFC-0001 -o plain
    govctl rfc show RFC-0001 -o yaml

NOTES:
    - Human-readable `show` hides deprecated RFC bodies and obsolete Clause bodies by default.
    - Use `--history` for complete archival human-readable content.
    - JSON, YAML, and TOML output stays complete and cannot be combined with `--history`.
    - Use `get` for field/path-level inspection.
")]
    Show(CommonShowArgs),
    /// Create a new RFC
    #[command(after_help = "\
EXAMPLES:
    govctl rfc new \"Add incremental index rebuilding\"
    govctl rfc new \"Add incremental index rebuilding\" --id RFC-0010

NOTES:
    - Use `--id` only when you need to pin a specific RFC ID.
    - New RFCs start as draft and can later be finalized.
")]
    New {
        /// RFC title
        title: String,
        /// RFC ID (e.g., RFC-0010). Auto-generated if omitted.
        #[arg(long)]
        id: Option<String>,
    },
    /// Canonical path-first edit entrypoint
    #[command(after_help = "\
EXAMPLES:
    govctl rfc edit RFC-0001 changelog.summary --set \"Clarify retry behavior\"
    govctl rfc edit RFC-0001 changelog.fixed --add \"Correct timeout wording\"
    govctl rfc edit RFC-0001 changelog.fixed[0] --remove
    govctl rfc edit RFC-0001 refs --add RFC-0002

NOTES:
    - Changelog edits apply only to the entry matching the RFC's current version.
    - RFC and changelog version/date fields are lifecycle-owned.
")]
    Edit(CommonEditArgs),
    /// Bump RFC version
    #[command(after_help = "\
EXAMPLES:
    govctl rfc bump RFC-0001 --patch -m \"Clarify examples\"
    govctl rfc bump RFC-0001 --minor -m \"Add a normative clause\" -c \"change: Define the new behavior\"
    govctl rfc bump RFC-0001 -c \"fix: Correct current-version wording\"

NOTES:
    - Version-changing bumps require a normative RFC in impl, test, or stable with a sealed signature.
    - While an RFC is in spec, continue authoring the current version candidate instead of bumping again.
    - Bump flags select literal SemVer components; they are not remapped impact labels.
    - For 0.y.z, use `--minor` for a breaking pre-1.0 amendment; `--major` deliberately advances to 1.0.0.
    - `--change` without a bump level updates the current changelog entry without changing version.
    - Use `-m/--summary` for a release summary and `-c/--change` for detailed entries.
")]
    Bump {
        /// RFC ID
        id: String,
        /// Patch version bump
        #[arg(long, group = "bump_level")]
        patch: bool,
        /// Minor version bump
        #[arg(long, group = "bump_level")]
        minor: bool,
        /// Major version bump
        #[arg(long, group = "bump_level")]
        major: bool,
        /// Changelog summary
        #[arg(short = 'm', long)]
        summary: Option<String>,
        /// Add change description(s)
        #[arg(short = 'c', long = "change")]
        changes: Vec<String>,
    },
    /// Finalize RFC status (draft → normative)
    #[command(after_help = "\
EXAMPLES:
    govctl rfc finalize RFC-0001 normative

NOTES:
    - Use `deprecate` for normative → deprecated.
    - Use `advance` to move phase after finalization.
")]
    Finalize {
        /// RFC ID
        id: String,
        /// Target status (`normative`)
        #[arg(value_enum)]
        status: FinalizeStatus,
    },
    /// Advance RFC phase
    #[command(after_help = "\
EXAMPLES:
    govctl rfc advance RFC-0001 impl
    govctl rfc advance RFC-0001 test

NOTES:
    - Typical progression is `spec -> impl -> test -> stable`.
    - Use this after the RFC has been finalized.
")]
    Advance {
        /// RFC ID
        id: String,
        /// Target phase
        #[arg(value_enum)]
        phase: RfcPhase,
    },
    /// Deprecate RFC
    #[command(after_help = "\
EXAMPLES:
    govctl rfc deprecate RFC-0001
    govctl rfc deprecate RFC-0001 --force
")]
    Deprecate(CommonDeprecateArgs),
    /// Supersede RFC
    #[command(after_help = "\
EXAMPLES:
    govctl rfc supersede RFC-0001 --by RFC-0002
    govctl rfc supersede RFC-0001 --by RFC-0002 --force
")]
    Supersede(CommonSupersedeArgs),
    /// Render a single RFC to markdown
    #[command(after_help = "\
EXAMPLES:
    govctl rfc render RFC-0001
    govctl rfc render RFC-0001 --dry-run
")]
    Render(CommonRenderArgs),
}