[TASK] Add concise README with workflow status

[CybotTM]

Summary

Reworked based on feedback. This is now README-only — no Documentation/ folder, no ADRs, no RST rendering.

What changed

• Workflow table with real-world adoption status (Production / Available)
• Backport secrets documented (APP_ID, APP_PRIVATE_KEY + why App token is needed)
• Usage example and migration guide
• Input/secret details live in the YAML files themselves

Diff

• Removed: 13 files in Documentation/ (RST docs, ADRs, guides.xml)
• Changed: README.md — from 215 lines to 56 lines

[linawolf]

The nessesary steps should be documented in the maintainer section of the How to document tutorial. And we should not make it overly complicated. I suggest not having them here.

[CybotTM]

Hi @linawolf

The nessesary steps should be documented in the maintainer section of the How to document tutorial. And we should not make it overly complicated. I suggest not having them here.

Can you please be more specific of what exact part of this PR you are talking?

Documentation should live with the project it documents, especially when it is tightly coupled to concrete workflow files, inputs, usage examples, and architectural decisions. Otherwise we create split ownership and the documentation will drift.

I agree that we should not duplicate generic maintainer guidance. That belongs in “How to document”. But the reference documentation for the shared reusable workflows belongs in this repository.

So I would keep the repo-specific documentation here and only move genuinely generic maintainer guidance to the tutorial.

But I am not sure what specific part of this PR you are referring to.

[linawolf]

Hi,

to clarify my point: I am not asking for moving parts of the documentation around — I am questioning the amount and form of documentation added in this PR.

For this repository, I only want a concise README, not an extensive multi-page documentation in a separate Documentation/ folder.

This repo is not intended to be used standalone, so it should not contain full-blown documentation. The maintainer guide remains the single source of truth for workflows and processes. This repository should only provide:

a short overview

the purpose of the workflows

their current status (e.g. backport = working, others = untested)

links to the central documentation and possibly example usages

What I want to avoid is creating and maintaining large amounts of documentation here, especially for workflows that are not yet fully implemented or validated.

To give some context: I spent several hours this weekend getting the reusable backport workflow actually working. Based on that experience, I expect the other proposed reusable workflows will require a similar level of effort before they are production-ready.

Right now, this PR introduces a large amount of documentation for workflows that are not yet tested. That makes reviewing difficult and creates the risk of documenting things that do not work in practice.

It would be much more helpful to focus on one workflow at a time, get it fully working and validated, and then document it concisely.

So my suggestion is to remove the extensive documentation folder from this PR and reduce this to a focused README.

Thanks!

[linawolf]

This should be boilded down to a short README as described above

[CybotTM]

Hi @linawolf,

got it, thanks for clarifying.

I still see it differently, for me a repo should be understandable and usable in isolation. That includes ADRs and some level of documentation close to the code, not just external docs.

But I get your point about scope and avoiding unvalidated docs here. Your repo, your rules — I’ll align 🙂

[CybotTM]

Reworked based on your feedback:

• Removed the entire Documentation/ folder (13 files, ~700 lines gone)
• README-only: concise workflow table with real-world status
• Backport secrets documented (the APP_ID/APP_PRIVATE_KEY setup you just got working)
• Each workflow is either "Production (8 repos)" or "Available" — no pretending untested workflows are proven

Input/secret details stay in the YAML files where they belong.