Improving visibility/clarity or repo status: using badge and better docs

[leogr]

Motivation

We have received feedback indicating that the current status of each repository (official, incubating, sandbox, etc.) needs to be sufficiently visible and clearly understood. So, there is a need to convey better the maturity level of each repository to enhance clarity for our users and contributors.

Feature

My proposal in this regard is to implement the following:

• [x] Revise our documentation to ensure these definitions and statuses are clearly described and consistently applied. Documentation should be adequately interlinked for easier navigation.

• [x] Add a badge to each repository, indicating its status (Stable, Incubating, Sandbox). This badge should link to a description of what each status means. (someone proposed this idea to me a couple of weeks ago - I would like to give credit to this person, but unfortunately, I can't recall who :sweat: )

Alternatives

Doing nothing is always an alternative :sweat_smile: However, if we do not make these changes, there could be ongoing confusion about the purpose and status of our repositories.

Additional context

The purpose is to ensure that our repository adoption model (that demonstrated to work fine) is not only transparent but also readily perceivable to all stakeholders. On top of that, we may also want to revise some statuses or create new ones to reflect the level of some particular repositories better. For example, I may argue that test-infra should not be considered "incubating" anymore. At the same time, it does not match the "core" definition.

Note: while revising the above points, other improvements come up. See https://github.com/falcosecurity/evolution/pull/273 for full details.

[leogr]

cc @falcosecurity/core-maintainers

[Issif]

Good to me. We also need to clarify the rules to change from one state to another.

[LucaGuerra]

+1 Sometimes users ask if a specific repo is in official status or not and even us maintainers need to check evolution at times. It should be easier to understand just by looking at the repo.

[maxgio92]

+1 for all.

Moreover, my 2 cents about maturity level vs scope below. Practically speaking, it might be good to make the semantic of adoption status more granular. In detail, from our documentation:

The Falco Project follows a simple adoption model for repositories. Each repository gets a status that indicates the level of adoption (ie. the maturity level) or, for particular repositories, its scope

TL;DR: it might be good to distinguish:

• maturity level, from
• scope.

In the example fo test-infra, maturity level would be the 3/3, but the scope: something not core/ecosystem.

WDYT?

[leogr]

Hey @maxgio92

TL;DR: it might be good to distinguish:

• maturity level, from
• scope.

In the example fo test-infra, maturity level would be the 3/3, but the scope: something not core/ecosystem.

WDYT?

What about this :point_down: ? https://github.com/falcosecurity/evolution/pull/273/files#diff-51c0832bebbbbe0b98ad16b4ce55159543043510b7fef947faa9a4ea3e5ebbc2R55-R69

[maxgio92]

Thank you @leogr! Looks good to me! I think it could also be unlocked (non WIP).

[leogr]

See https://github.com/falcosecurity/evolution/pull/273

Next steps: I will open PRs to add badges to READMEs of each single repo :smile_cat:

[leogr]

This has been addressed.