opencommit/roadmap

Auto-README Updater (Action) #9

New issue

Open

opened 2026-04-11 23:14:51 +02:00 by mvdkleijn · 0 comments

mvdkleijn commented

2026-04-11 23:14:51 +02:00

Owner

1. What

Development of a Forgejo Action designed to automate the injection of dynamic metadata into repository README.md files. This action allows developers to programmatically update critical project information, such as version numbers, as part of their existing CI/distributed workflows, ensuring that project documentation is always synchronized with the codebase.

2. Why

Workflow Integration: Empowers developers to integrate documentation updates directly into their existing CI/CD pipelines, treating documentation as code.
Reduced Documentation Rot: Prevents "stale" information in READMEs by automating the most tedious parts of the release and deployment process.
Standardized Excellence: Encourages a high standard of project presentation across the OpenCommit ecosystem by making "professional-looking" READMEs easy to maintain.
Low-Friction Adoption: As a Forgejo Action, it requires no platform-level permission changes or complex setup, only a simple addition to a .forgejo/workflows file.

3. Boundaries

In-Scope:
- Regex-based Injection: Logic to locate and replace text.
- Multi-Source Input: Ability to accept inputs from previous workflow steps (e.g., a step that calculates a version number or checks a build status).
- Git Automation: Handling the heavy lifting of git checkout, git commit, and git push within the runner environment.
- Customizable Metadata: Support for user-defined keys and values via the action's with: configuration block.
Out-of-Scope:
- Complex Markdown Parsing: The action will not attempt to "understand" the logic of the README; it strictly operates on defined regex-es.

4. Definition of Done

Workflow Compatibility: The action can be successfully executed within a standard Forgejo Actions runner.
Configuration Flexibility: Users can define custom input keys and values via the with: syntax in their YAML workflow files.
Replacement Integrity: The action correctly updates only the designated content, leaving the rest of the README.md untouched.
Atomic Commits: Each run produces a clean, single-purpose commit that is easily reversible and does not clutter the Git history with broken formatting.
Error Handling: The action fails gracefully and provides clear error logs if anything goes wrong.

## **1. What** Development of a Forgejo Action designed to automate the injection of dynamic metadata into repository `README.md` files. This action allows developers to programmatically update critical project information, such as version numbers, as part of their existing CI/distributed workflows, ensuring that project documentation is always synchronized with the codebase. ## **2. Why** * **Workflow Integration:** Empowers developers to integrate documentation updates directly into their existing CI/CD pipelines, treating documentation as code. * **Reduced Documentation Rot:** Prevents "stale" information in READMEs by automating the most tedious parts of the release and deployment process. * **Standardized Excellence:** Encourages a high standard of project presentation across the OpenCommit ecosystem by making "professional-looking" READMEs easy to maintain. * **Low-Friction Adoption:** As a Forgejo Action, it requires no platform-level permission changes or complex setup, only a simple addition to a `.forgejo/workflows` file. ## **3. Boundaries** * **In-Scope:** * **Regex-based Injection:** Logic to locate and replace text. * **Multi-Source Input:** Ability to accept inputs from previous workflow steps (e.g., a step that calculates a version number or checks a build status). * **Git Automation:** Handling the heavy lifting of `git checkout`, `git commit`, and `git push` within the runner environment. * **Customizable Metadata:** Support for user-defined keys and values via the action's `with:` configuration block. * **Out-of-Scope:** * **Complex Markdown Parsing:** The action will not attempt to "understand" the logic of the README; it strictly operates on defined regex-es. ## **4. Definition of Done** * [ ] **Workflow Compatibility:** The action can be successfully executed within a standard Forgejo Actions runner. * [ ] **Configuration Flexibility:** Users can define custom input keys and values via the `with:` syntax in their YAML workflow files. * [ ] **Replacement Integrity:** The action correctly updates only the designated content, leaving the rest of the `README.md` untouched. * [ ] **Atomic Commits:** Each run produces a clean, single-purpose commit that is easily reversible and does not clutter the Git history with broken formatting. * [ ] **Error Handling:** The action fails gracefully and provides clear error logs if anything goes wrong.