From e8290844bb87246796d0da6a424fb763cea6bcfa Mon Sep 17 00:00:00 2001 From: Twan Goosen Date: Mon, 28 Oct 2024 10:08:58 +0100 Subject: [PATCH] put some things in the right place + updated ToC --- docs/general-guidelines/maintenance.md | 60 +++++++++++++++++++ .../localisation.md | 0 docs/maintenance.md | 60 ------------------- mkdocs.yml | 3 + 4 files changed, 63 insertions(+), 60 deletions(-) rename {interoperability-and-portability => docs/interoperability-and-portability}/localisation.md (100%) delete mode 100644 docs/maintenance.md diff --git a/docs/general-guidelines/maintenance.md b/docs/general-guidelines/maintenance.md index e69de29..2e93e11 100644 --- a/docs/general-guidelines/maintenance.md +++ b/docs/general-guidelines/maintenance.md @@ -0,0 +1,60 @@ +## Maintenance + +Project statuses + +- Prototype +- Active development +- Maint +- Deprecated - deployed +- Deprecated - undeployed + +

Label

Development

Maintenance

Deployed

Notes

A

+

+

-

Prototyping to first RC

B

+

+

+

Matur(ing), in use

At least one stable release

C

-

+

+

Stable, feature frozen

D

-

-

+

Abandoned, in use

E

-

-

-

Dead

+ +Definitions + +- Development + - There is a development roadmap specific to the dev project + - Has at least one responsible developer assigned +- Maintenance + - Has at least one responsible maintainer assigned + - Responsible for monitoring code base in terms of vulnerabilities, functional breakages + - Responsible for addressing (at the very least) critical issues in the code base + - Example activities covered + - Dependency / base image updates + - Implement required adaptations to new or changed context (OS, runtime, servlet container, ...) + +

Status


Project examples

A

Prototyping - first RC

VCR JS widget

VLO 5.0

DOG

B

Matur(ing), in use

VLO

VCR

C

Stable, feature frozen

Switchboard

Component Registry

Centre Registry

OAI-PMH Harvester, viewer

RASA

D

Abandoned, in use

SAML-metadata-checker

earlier: FCS?

E

Dead

clarin-horizon_drupal_theme

+ +\[TODO: guidelines matrix for status X aspect\] + +Per project status: + +- What drives releases? + - A-B: roadmap + - C: external factors, e.g. support for underlying technology, fixing of critical bugs and vulnerabilities + - D-E: n/a +- Maintainer(s) - tasks and responsibilities + - A-C MUST address critical security risks + - CAN address other issues + - enhancements and new functionality covered by developer role! + - No maintainer (cat D, E) -> operational handbook + - Possibility to (temporarily) address as C in short term + - OR (temporarily) shut down +- Repository + - Cat A-C: MUST be findable in Git repositories + - D: SHOULD be in Git repository, MAY be in deprecated repository system + - E: SHOULD be archived +- Issue reporting & tracking + - A-B: known issues, envisioned features are documented in issue tracking system by developer/maintainer + - may be for C as well but without commitment + - A-B-C: maintainer will handle incoming issue reports via repository system + - D-E: issue reporting is disabled +- Documentation + - A: needs to have minimal documentation (needs to be defined) for development, deployment, testing purposes (up-to-date README file) + - B-C: need to have up-to-date documentation both for development and operational purposes and end users; changelog + - D-E: documentation needs to include statement about status of project +- Monitoring -> operational + - B-C: needs permanent monitoring with alerting, log aggregation to ensure good health + - D: included in general monitoring to ensure being alive + + diff --git a/interoperability-and-portability/localisation.md b/docs/interoperability-and-portability/localisation.md similarity index 100% rename from interoperability-and-portability/localisation.md rename to docs/interoperability-and-portability/localisation.md diff --git a/docs/maintenance.md b/docs/maintenance.md deleted file mode 100644 index 2e93e11..0000000 --- a/docs/maintenance.md +++ /dev/null @@ -1,60 +0,0 @@ -## Maintenance - -Project statuses - -- Prototype -- Active development -- Maint -- Deprecated - deployed -- Deprecated - undeployed - -

Label

Development

Maintenance

Deployed

Notes

A

+

+

-

Prototyping to first RC

B

+

+

+

Matur(ing), in use

At least one stable release

C

-

+

+

Stable, feature frozen

D

-

-

+

Abandoned, in use

E

-

-

-

Dead

- -Definitions - -- Development - - There is a development roadmap specific to the dev project - - Has at least one responsible developer assigned -- Maintenance - - Has at least one responsible maintainer assigned - - Responsible for monitoring code base in terms of vulnerabilities, functional breakages - - Responsible for addressing (at the very least) critical issues in the code base - - Example activities covered - - Dependency / base image updates - - Implement required adaptations to new or changed context (OS, runtime, servlet container, ...) - -

Status


Project examples

A

Prototyping - first RC

VCR JS widget

VLO 5.0

DOG

B

Matur(ing), in use

VLO

VCR

C

Stable, feature frozen

Switchboard

Component Registry

Centre Registry

OAI-PMH Harvester, viewer

RASA

D

Abandoned, in use

SAML-metadata-checker

earlier: FCS?

E

Dead

clarin-horizon_drupal_theme

- -\[TODO: guidelines matrix for status X aspect\] - -Per project status: - -- What drives releases? - - A-B: roadmap - - C: external factors, e.g. support for underlying technology, fixing of critical bugs and vulnerabilities - - D-E: n/a -- Maintainer(s) - tasks and responsibilities - - A-C MUST address critical security risks - - CAN address other issues - - enhancements and new functionality covered by developer role! - - No maintainer (cat D, E) -> operational handbook - - Possibility to (temporarily) address as C in short term - - OR (temporarily) shut down -- Repository - - Cat A-C: MUST be findable in Git repositories - - D: SHOULD be in Git repository, MAY be in deprecated repository system - - E: SHOULD be archived -- Issue reporting & tracking - - A-B: known issues, envisioned features are documented in issue tracking system by developer/maintainer - - may be for C as well but without commitment - - A-B-C: maintainer will handle incoming issue reports via repository system - - D-E: issue reporting is disabled -- Documentation - - A: needs to have minimal documentation (needs to be defined) for development, deployment, testing purposes (up-to-date README file) - - B-C: need to have up-to-date documentation both for development and operational purposes and end users; changelog - - D-E: documentation needs to include statement about status of project -- Monitoring -> operational - - B-C: needs permanent monitoring with alerting, log aggregation to ensure good health - - D: included in general monitoring to ensure being alive - - diff --git a/mkdocs.yml b/mkdocs.yml index 3294c3d..1a06a4c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,3 +49,6 @@ nav: - 'Docker': stack/docker.md - 'Python': stack/python.md - 'Javascript': stack/javascript.md + - 'Interoperability and portability': + - 'Authentication mechanisms': interoperability-and-portability/authentication-mechanisms.md + - 'Localisation and internationaliszation': interoperability-and-portability/localisation.md