From 1fa5a57df1ff98e7f55a81029f3679e209e4c6d0 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 14:10:53 +0200 Subject: [PATCH 01/15] Fix broken link --- content/collections/reference/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index 06a1191d..f684ae42 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -207,7 +207,7 @@ fr: {{< refItem name="roles" type="array of strings" - description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/references/governance/)" + description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)" allowedValues="host, administrator, curator, maintainer, sponsor" example="[host, administrator]" required=true From 7783819172a120d737fbb03b3bdf6bd7146005a0 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 14:12:09 +0200 Subject: [PATCH 02/15] Improve URL --- content/community/how-to/{join-community-chat.md => join.md} | 1 + 1 file changed, 1 insertion(+) rename content/community/how-to/{join-community-chat.md => join.md} (98%) diff --git a/content/community/how-to/join-community-chat.md b/content/community/how-to/join.md similarity index 98% rename from content/community/how-to/join-community-chat.md rename to content/community/how-to/join.md index 425d9f8b..5ad18c0d 100644 --- a/content/community/how-to/join-community-chat.md +++ b/content/community/how-to/join.md @@ -3,6 +3,7 @@ title: Join the community chat aliases: - /community/how-to-join-mattermost/ - /community/how-to/join-mattermost/ + - /community/how-to/join-community-chat/ linkTitle: Join the chat --- From 35bb81d5dbc003a22206b4efe5915ffc64063409 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 14:54:21 +0200 Subject: [PATCH 03/15] Add collection status reference --- content/collections/reference/status.md | 82 +++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 content/collections/reference/status.md diff --git a/content/collections/reference/status.md b/content/collections/reference/status.md new file mode 100644 index 00000000..2443bf2d --- /dev/null +++ b/content/collections/reference/status.md @@ -0,0 +1,82 @@ +--- +title: Status +weight: 5 +--- + +# Collection Status + +This reference documentation outlines the different status levels that a collection can have within the system. Understanding these statuses is crucial for users to assess a collection's reliability, maintenance level, and current operational state. + +## Status types + +Each status represents a distinct state of collection health and maintenance, ranging from fully operational to terminated. + +### `Active` +The optimal operational state for a collection. + +##### ✅ Operational characteristics +- Regular record saving +- Terms declarations actively maintained and updated +- Consistent growth or stability in tracked terms +- High and stable tracking quality + +##### ✅ Technical maintenance +- Regular dependency updates +- Access to latest engine features +- Benefits from infrastructure updates + +##### ✅ Team status +- All roles are filled and active + +--- + +### `Maintenance requested` + +Indicates a collection that needs attention but remains functional. + +##### ⚠️ Operational characteristics + +- Regular record saving +- Limited or no updates to terms declarations +- Declining number of tracked terms +- Decreasing tracking quality + +##### ✅ Technical maintenance + +- Critical dependency updates maintained +- Access to latest engine features +- Benefits from infrastructure updates + +##### ⚠️ Team status + +- Host and administrator remain active +- Curators and maintainers are inactive + +--- + +### `Abandoned` + +Collection is functional but showing signs of neglect. + +##### ❌ Operational characteristics + +- Unknown record saving status +- No updates to terms declarations +- Declining number of tracked terms +- Decreasing tracking quality + +##### ❌ Technical maintenance + +- No dependency updates +- Missing latest engine features +- Missing infrastructure updates + +##### ❌ Team status + +- All roles are inactive + +--- + +### `Terminated` + +Collection has ceased operations, it cannot be used for new records but may still be accessible for historical reference. Tracking quality reflects the collection's maintenance level during its active period. From af89aed29a2064a7aea5066597ab6628fb4361a8 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 16:30:59 +0200 Subject: [PATCH 04/15] Refactor Collection status reference --- content/collections/reference/status.md | 73 ++++++++++--------------- 1 file changed, 28 insertions(+), 45 deletions(-) diff --git a/content/collections/reference/status.md b/content/collections/reference/status.md index 2443bf2d..6d18057a 100644 --- a/content/collections/reference/status.md +++ b/content/collections/reference/status.md @@ -7,76 +7,59 @@ weight: 5 This reference documentation outlines the different status levels that a collection can have within the system. Understanding these statuses is crucial for users to assess a collection's reliability, maintenance level, and current operational state. -## Status types +## Status Overview -Each status represents a distinct state of collection health and maintenance, ranging from fully operational to terminated. +| Status | Tracking | Engine and infrastructure updates | Roles activity | Quality | +|:-----------------|:---------|:------------|:-----------|:------------| +| `Active` | ✅ Operational | ✅ All | ✅ All | ✅ Stable | +| `Maintenance requested` | ⚠️ May have interupts | ⚠️ Critical only | ⚠️ Admin only | ⚠️ Decreasing | +| `Abandoned` | ⚠️ Unknown | ❌ None | ❌ None | ❌ Poor | +| `Terminated` | ❌ Stopped | N/A | N/A | Depends on maintenance level during active period | + +## Detailed status descriptions ### `Active` -The optimal operational state for a collection. -##### ✅ Operational characteristics -- Regular record saving -- Terms declarations actively maintained and updated -- Consistent growth or stability in tracked terms -- High and stable tracking quality +- The optimal operational state for a collection. + +- The collection maintains regular record saving with actively maintained and updated terms declarations. The number of tracked terms remains stable or increases over time. The tracking quality is high and stable. -##### ✅ Technical maintenance -- Regular dependency updates -- Access to latest engine features -- Benefits from infrastructure updates +- Technical maintenance includes regular dependency updates, access to the latest engine features, and benefits from all infrastructure updates. -##### ✅ Team status -- All roles are filled and active +- All roles filled and active. --- ### `Maintenance requested` -Indicates a collection that needs attention but remains functional. - -##### ⚠️ Operational characteristics - -- Regular record saving -- Limited or no updates to terms declarations -- Declining number of tracked terms -- Decreasing tracking quality - -##### ✅ Technical maintenance +- Indicates a collection that needs attention but remains functional. -- Critical dependency updates maintained -- Access to latest engine features -- Benefits from infrastructure updates +- Regular record saving continues, however, the collection shows signs of strain with limited or no updates to terms declarations. The number of tracked terms is declining, and tracking quality is decreasing. -##### ⚠️ Team status +- Technical maintenance continues but at a reduced level, critical dependency updates are applied, though often with delays. The collection maintains access to essential engine features and infrastructure updates to ensure basic functionality, but may not receive all new feature improvements. -- Host and administrator remain active -- Curators and maintainers are inactive +- Some roles are inactive; while hosts and administrators remain partially active, curators and maintainers have become inactive. --- ### `Abandoned` -Collection is functional but showing signs of neglect. +- Collection may be functional but shows clear signs of neglect. -##### ❌ Operational characteristics +- Operational status has deteriorated significantly with unknown record saving status, no updates to terms declarations, declining number of tracked terms, and decreasing tracking quality. -- Unknown record saving status -- No updates to terms declarations -- Declining number of tracked terms -- Decreasing tracking quality +- Technical maintenance has ceased completely, with no dependency updates, missing latest engine features, and no infrastructure updates. -##### ❌ Technical maintenance +- All roles are inactive. -- No dependency updates -- Missing latest engine features -- Missing infrastructure updates +--- -##### ❌ Team status +### `Terminated` -- All roles are inactive +- Collection has ceased all operational activities. ---- +- Record saving is no longer active, though historical records remain accessible for reference purposes. -### `Terminated` +- No technical maintenance is performed as the collection is no longer operational. -Collection has ceased operations, it cannot be used for new records but may still be accessible for historical reference. Tracking quality reflects the collection's maintenance level during its active period. +- No active roles exist as the collection is terminated. From d421bb35a879034dbb990267c4e39834a743d78a Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 17:45:49 +0200 Subject: [PATCH 05/15] Add guide to take over abandoned collection --- content/collections/how-to/take-over.md | 26 +++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 content/collections/how-to/take-over.md diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md new file mode 100644 index 00000000..ebb3db6d --- /dev/null +++ b/content/collections/how-to/take-over.md @@ -0,0 +1,26 @@ +--- +title: Take over abandoned collection +weight: 2 +--- + +# How to take over maintenance of abandoned collection + +Before starting, ensure the collection is [abandoned]({{< relref "collections/reference/status#abandoned" >}}). + +## Steps + +1. Get owners' approval by contacting them via email if publicly available, a GitHub issue on the collection repository or on the [community chat]({{< relref "federation/how-to/join" >}}). + +2. Ask the owner to transfer the repositories to your organization. + +3. Verify that the declarations, snapshots and versions repositories are transferred and properly configured by taking a look at [this guide]({{< relref "collections/how-to/create-repositories/" >}}). + +3. Update Readme, and follow [this guide to update collection metadata]({{< relref "collections/how-to/define-metadata" >}}) inside the declarations repository. + +4. Follow [this guide to deploy the collection]({{< relref "deployment/how-to/deploy" >}}) on your server. + +5. Ensure continous integration and deployment is working. + +Congratulations! You can now start maintaining the collection. + +Keep original licenses and attributions. From 8416df9026019cbdad6c4b0e305f73cbf71ce71b Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 8 Apr 2025 17:49:20 +0200 Subject: [PATCH 06/15] Fix links --- content/collections/how-to/take-over.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index ebb3db6d..ef0012d9 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -13,11 +13,11 @@ Before starting, ensure the collection is [abandoned]({{< relref "collections/re 2. Ask the owner to transfer the repositories to your organization. -3. Verify that the declarations, snapshots and versions repositories are transferred and properly configured by taking a look at [this guide]({{< relref "collections/how-to/create-repositories/" >}}). +3. Verify that the declarations, snapshots and versions repositories are transferred and properly configured by taking a look at [this guide]({{< relref "/collections/how-to/create-repositories" >}}). -3. Update Readme, and follow [this guide to update collection metadata]({{< relref "collections/how-to/define-metadata" >}}) inside the declarations repository. +3. Update Readme, and follow [this guide to update collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) inside the declarations repository. -4. Follow [this guide to deploy the collection]({{< relref "deployment/how-to/deploy" >}}) on your server. +4. Follow [this guide to deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your server. 5. Ensure continous integration and deployment is working. From 601027b5b279c3d4dba7819bd41621b30209a8eb Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 09:24:35 +0200 Subject: [PATCH 07/15] Improve how to take over a collection --- content/collections/how-to/take-over.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index ef0012d9..1a1d9290 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -15,11 +15,11 @@ Before starting, ensure the collection is [abandoned]({{< relref "collections/re 3. Verify that the declarations, snapshots and versions repositories are transferred and properly configured by taking a look at [this guide]({{< relref "/collections/how-to/create-repositories" >}}). -3. Update Readme, and follow [this guide to update collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) inside the declarations repository. +4. Update the README.md file, and follow [this guide to update collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) inside the declarations repository. -4. Follow [this guide to deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your server. +5. Follow [this guide to deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your server. -5. Ensure continous integration and deployment is working. +6. Ensure continous integration and deployment is working. Congratulations! You can now start maintaining the collection. From 94fc4e4a6c53f46c5de094d83ea0e8c2a4b625fd Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 17:10:29 +0200 Subject: [PATCH 08/15] Simplify status to prevent them from being falsely exhaustive --- content/collections/reference/status.md | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/content/collections/reference/status.md b/content/collections/reference/status.md index 6d18057a..2a8b9709 100644 --- a/content/collections/reference/status.md +++ b/content/collections/reference/status.md @@ -3,21 +3,10 @@ title: Status weight: 5 --- -# Collection Status +# Collection status This reference documentation outlines the different status levels that a collection can have within the system. Understanding these statuses is crucial for users to assess a collection's reliability, maintenance level, and current operational state. -## Status Overview - -| Status | Tracking | Engine and infrastructure updates | Roles activity | Quality | -|:-----------------|:---------|:------------|:-----------|:------------| -| `Active` | ✅ Operational | ✅ All | ✅ All | ✅ Stable | -| `Maintenance requested` | ⚠️ May have interupts | ⚠️ Critical only | ⚠️ Admin only | ⚠️ Decreasing | -| `Abandoned` | ⚠️ Unknown | ❌ None | ❌ None | ❌ Poor | -| `Terminated` | ❌ Stopped | N/A | N/A | Depends on maintenance level during active period | - -## Detailed status descriptions - ### `Active` - The optimal operational state for a collection. @@ -30,18 +19,6 @@ This reference documentation outlines the different status levels that a collect --- -### `Maintenance requested` - -- Indicates a collection that needs attention but remains functional. - -- Regular record saving continues, however, the collection shows signs of strain with limited or no updates to terms declarations. The number of tracked terms is declining, and tracking quality is decreasing. - -- Technical maintenance continues but at a reduced level, critical dependency updates are applied, though often with delays. The collection maintains access to essential engine features and infrastructure updates to ensure basic functionality, but may not receive all new feature improvements. - -- Some roles are inactive; while hosts and administrators remain partially active, curators and maintainers have become inactive. - ---- - ### `Abandoned` - Collection may be functional but shows clear signs of neglect. From 732bdb336875d02400e60a4d741f90af16e0d20c Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 17:10:45 +0200 Subject: [PATCH 09/15] Improve how to take over a collection --- content/collections/how-to/take-over.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index 1a1d9290..65093b17 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -1,15 +1,15 @@ --- -title: Take over abandoned collection +title: Take over a collection weight: 2 --- -# How to take over maintenance of abandoned collection +# How to take over a collection -Before starting, ensure the collection is [abandoned]({{< relref "collections/reference/status#abandoned" >}}). +Before starting, ensure the collection is [abandoned]({{< relref "collections/reference/status#abandoned" >}}) or [terminated]({{< relref "collections/reference/status#terminated" >}}). ## Steps -1. Get owners' approval by contacting them via email if publicly available, a GitHub issue on the collection repository or on the [community chat]({{< relref "federation/how-to/join" >}}). +1. If the approval is not explicitly given in the collection's README.md file, get it by contacting owners via email if publicly available, a GitHub issue on the collection repository or on the [community chat]({{< relref "federation/how-to/join" >}}). 2. Ask the owner to transfer the repositories to your organization. From b1f19b36f9816d34df0a7c9b51d36125f3d5edce Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 17:10:56 +0200 Subject: [PATCH 10/15] Add how to terminate a collection --- content/collections/how-to/terminate.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 content/collections/how-to/terminate.md diff --git a/content/collections/how-to/terminate.md b/content/collections/how-to/terminate.md new file mode 100644 index 00000000..0eb30bcd --- /dev/null +++ b/content/collections/how-to/terminate.md @@ -0,0 +1,24 @@ +--- +title: Terminate a collection +weight: 3 +--- + +# How to terminate a collection + +Follow these steps to properly terminate a collection you own, making it clear to users and potential successors that it is no longer actively maintained and can be taken over. + +## Steps + +1. Announce the intention to terminate the collection in the [community chat]({{< relref "/federation/how-to/join" >}}) to inform users and make potential new maintainers aware. Let some time, one month is recommended, for users to explicit their intenttion to take over the collection before proceeding to the next step. + +If no-one has come forward after one month, you can proceed to the next step. + +2. In the declarations repository's main `README.md` file, state that the collection is [terminated]({{< relref "collections/reference/status#terminated" >}}), encourage community to [take it over]({{< relref "collections/how-to/take-over" >}}). It can be done by adding the following snippet on the top of the file: + +``` +This collection is no longer actively maintained. If you are interested in taking over maintenance, please let us know in the [community chat]({{< relref "/federation/how-to/join" >}}). +``` + +3. [Archive the collection's repositories](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) (declarations, snapshots, versions) to prevent further commits and signal the end of activity. + +Once these steps are completed, the collection is officially terminated. It remains accessible but marked as inactive. From 429329c8974f3495ea20f8a7e1216562f5ec127b Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 17:11:47 +0200 Subject: [PATCH 11/15] Improve collection governance reference --- content/collections/reference/governance.md | 72 +++++++++++++++++---- 1 file changed, 60 insertions(+), 12 deletions(-) diff --git a/content/collections/reference/governance.md b/content/collections/reference/governance.md index 1019b9a7..464f004f 100644 --- a/content/collections/reference/governance.md +++ b/content/collections/reference/governance.md @@ -10,26 +10,74 @@ Setting up and maintaining a collection needs fulfilling certain tasks. These ta This reference documentation details all available roles that can be involved in a collection's governance to ensure its proper operation and maintenance. -### Host +## Roles -This role ensures that a server and internet access is available to run the engine on and fetch the terms, either by using its own infrastructure or renting a server on a hosting provider. +### `Host` -### Administrator +Ensures the foundational infrastructure required for the collection's operation is available. -This role takes responsibility for ensuring that the engine and associated software tools are functional and up to date. +**Responsibilities:** -### Curator +- Provide the server infrastructure (self-hosted or rented). +- Guarantee reliable internet connectivity for the server to fetch terms. -This role decides which services and terms are welcome in the collection. +--- + +### `Administrator` + +Manages the technical operation of the collection's software, ensuring it runs smoothly, stays updated, and remains secure. + +**Responsibilities:** + +- Keep the engine operational. +- Ensure terms are tracked. +- Ensure the public publishing of snapshots, versions, and datasets. +- Maintain and update the engine-related infrastructure. +- Apply necessary security patches to the infrastructure. + +--- + +### `Curator` + +Defines the collection's focus and ensures all included content aligns with that scope. -### Maintainer +**Responsibilities:** + +- Clearly define the collection's scope. +- Make the collection scope publicly available via the metadata file. +- Verify that included services and terms adhere to the defined scope. + +--- -This role guarantees the quality of the tracked versions by reviewing contributions. +### `Maintainer` + +Guarantees the integrity and quality of the collection's data by reviewing incoming contributions. + +**Responsibilities:** + +- Review contributions. +- Maintain the quality of tracked versions (e.g., removing noise, ensuring completeness). + +--- + +### `Contributor` + +Actively adds new service information and keeps existing entries current. + +**Responsibilities:** + +- Add service declarations. +- Keep service declarations up to date. + +--- -### Contributor +### `Sponsor` -This role adds declarations and keeps them up to date. +Provides essential non-operational support, such as funding or resources, to facilitate the collection's success. -### Sponsor +**Responsibilities:** -This optional role supports the existence of the collection by funding other roles, providing agent time, political support, or any other relevant non-operational contribution. +- Provide funding for collection operations. +- Provide agent time for other roles. +- Provide political or institutional support. +- Make other relevant non-operational contributions. From b36d6a7487fb0db38600fbc77e6eecb475b07a9b Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 9 Apr 2025 17:24:26 +0200 Subject: [PATCH 12/15] Reorder menu item and improve slug names --- content/collections/how-to/create-repositories.md | 2 +- content/collections/how-to/create.md | 2 +- content/collections/how-to/define-metadata.md | 2 +- content/collections/how-to/take-over.md | 2 +- content/collections/reference/configuration.md | 2 +- content/collections/reference/environment-variables.md | 2 +- content/collections/reference/governance.md | 2 +- content/collections/reference/metadata.md | 2 +- content/terms/how-to/be-notified.md | 4 +++- .../how-to/get-the-validUntil-date-from-an-issue.md | 3 ++- content/terms/how-to/rename-a-service.md | 3 ++- content/terms/how-to/terminate-a-service.md | 1 + .../how-to/{test-declaration.md => test-declarations.md} | 9 ++++++--- .../{add-terms-using-UI.md => track-terms-using-UI.md} | 8 +++++--- .../terms/how-to/{track-new-terms.md => track-terms.md} | 3 ++- 15 files changed, 29 insertions(+), 18 deletions(-) rename content/terms/how-to/{test-declaration.md => test-declarations.md} (90%) rename content/terms/how-to/{add-terms-using-UI.md => track-terms-using-UI.md} (80%) rename content/terms/how-to/{track-new-terms.md => track-terms.md} (99%) diff --git a/content/collections/how-to/create-repositories.md b/content/collections/how-to/create-repositories.md index b9b2b3d9..8884aedd 100644 --- a/content/collections/how-to/create-repositories.md +++ b/content/collections/how-to/create-repositories.md @@ -1,6 +1,6 @@ --- title: Create repositories -weight: 1 +weight: 2 --- # How to create collection repositories diff --git a/content/collections/how-to/create.md b/content/collections/how-to/create.md index 2fb1ccd0..c48a4295 100644 --- a/content/collections/how-to/create.md +++ b/content/collections/how-to/create.md @@ -1,6 +1,6 @@ --- title: Create a collection -weight: 3 +weight: 1 --- # How to create a collection diff --git a/content/collections/how-to/define-metadata.md b/content/collections/how-to/define-metadata.md index bffe5c67..d4d8817b 100644 --- a/content/collections/how-to/define-metadata.md +++ b/content/collections/how-to/define-metadata.md @@ -1,6 +1,6 @@ --- title: Define metadata -weight: 2 +weight: 3 --- # How to define metadata diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index 65093b17..d859408b 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -1,6 +1,6 @@ --- title: Take over a collection -weight: 2 +weight: 4 --- # How to take over a collection diff --git a/content/collections/reference/configuration.md b/content/collections/reference/configuration.md index e5be913b..ec4be876 100644 --- a/content/collections/reference/configuration.md +++ b/content/collections/reference/configuration.md @@ -1,6 +1,6 @@ --- title: Configuration -weight: 2 +weight: 3 --- # Configuration options diff --git a/content/collections/reference/environment-variables.md b/content/collections/reference/environment-variables.md index c17178bc..4c84277d 100644 --- a/content/collections/reference/environment-variables.md +++ b/content/collections/reference/environment-variables.md @@ -1,6 +1,6 @@ --- title: Environment variables -weight: 3 +weight: 4 --- ## Environment variables diff --git a/content/collections/reference/governance.md b/content/collections/reference/governance.md index 464f004f..9739fc58 100644 --- a/content/collections/reference/governance.md +++ b/content/collections/reference/governance.md @@ -1,6 +1,6 @@ --- title: Governance -weight: 4 +weight: 1 aliases: /collections/governance/ --- diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index f684ae42..b124420a 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -1,6 +1,6 @@ --- title: Metadata -weight: 1 +weight: 2 aliases: /collections/metadata/ --- diff --git a/content/terms/how-to/be-notified.md b/content/terms/how-to/be-notified.md index b9b9dd5f..e9e93929 100644 --- a/content/terms/how-to/be-notified.md +++ b/content/terms/how-to/be-notified.md @@ -1,5 +1,7 @@ --- -title: Be notified of terms changes +title: How to be notified of terms changes +weight: 4 +linkTitle: Be notified of changes aliases: - /subscribe-rss/ - /terms/how-to-be-notified-of-terms-changes/ diff --git a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md index 4478d4b2..5832e727 100644 --- a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md +++ b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md @@ -1,6 +1,7 @@ --- -title: How to get the `validUntil` +title: How to get the `validUntil` date linkTitle: Get the `validUntil` date +weight: 7 --- # How to get the `validUntil` date diff --git a/content/terms/how-to/rename-a-service.md b/content/terms/how-to/rename-a-service.md index 59871a5c..9b091b5f 100644 --- a/content/terms/how-to/rename-a-service.md +++ b/content/terms/how-to/rename-a-service.md @@ -1,8 +1,9 @@ --- title: How to rename a service linkTitle: Rename a service +weight: 5 --- # How to rename a service -The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms. +The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to/track-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms. diff --git a/content/terms/how-to/terminate-a-service.md b/content/terms/how-to/terminate-a-service.md index 7c3a923b..91f456a6 100644 --- a/content/terms/how-to/terminate-a-service.md +++ b/content/terms/how-to/terminate-a-service.md @@ -1,6 +1,7 @@ --- title: How to terminate a service linkTitle: Terminate a service +weight: 6 --- # How to terminate a service diff --git a/content/terms/how-to/test-declaration.md b/content/terms/how-to/test-declarations.md similarity index 90% rename from content/terms/how-to/test-declaration.md rename to content/terms/how-to/test-declarations.md index 22589203..fdff130c 100644 --- a/content/terms/how-to/test-declaration.md +++ b/content/terms/how-to/test-declarations.md @@ -1,9 +1,12 @@ --- -title: "Test your declarations" -weight: 4 +title: How to test your declarations +weight: 3 +linkTitle: Test declarations +aliases: + - /terms/how-to/test-declaration/ --- -# Test your declarations +# How to test your declarations When creating or modifying service declarations, it’s important to verify they work as expected before starting to track in production. The Open Terms Archive engine provides automated testing tools to that end. diff --git a/content/terms/how-to/add-terms-using-UI.md b/content/terms/how-to/track-terms-using-UI.md similarity index 80% rename from content/terms/how-to/add-terms-using-UI.md rename to content/terms/how-to/track-terms-using-UI.md index bfafa6e2..80e3bcce 100644 --- a/content/terms/how-to/add-terms-using-UI.md +++ b/content/terms/how-to/track-terms-using-UI.md @@ -1,11 +1,13 @@ --- -title: Add terms with the graphical contribution interface -linkTitle: Add terms with UI +title: How to track terms using the graphical contribution interface +weight: 2 +linkTitle: Track terms with UI aliases: - /terms/how-to-add-terms-using-with-the-graphical-contribution-interface/ + - /terms/how-to/add-terms-using-ui/ --- -# How to add terms with the graphical contribution interface +# How to track terms using the graphical contribution interface ## Screencast diff --git a/content/terms/how-to/track-new-terms.md b/content/terms/how-to/track-terms.md similarity index 99% rename from content/terms/how-to/track-new-terms.md rename to content/terms/how-to/track-terms.md index a936fec2..5946b964 100644 --- a/content/terms/how-to/track-new-terms.md +++ b/content/terms/how-to/track-terms.md @@ -1,8 +1,9 @@ --- title: Track new terms -weight: 2 +weight: 1 aliases: - /contributing-terms/ + - /terms/how-to/track-new-terms/ --- # How to track new terms From ffa838ca440c12af9f22a25964c0855399929253 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Thu, 10 Apr 2025 10:24:58 +0200 Subject: [PATCH 13/15] Improve copywriting --- content/collections/how-to/take-over.md | 18 +++----- content/collections/how-to/terminate.md | 14 +++--- content/collections/reference/governance.md | 49 ++++++++++----------- content/collections/reference/status.md | 34 ++++++-------- 4 files changed, 51 insertions(+), 64 deletions(-) diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index d859408b..38458db5 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -5,22 +5,18 @@ weight: 4 # How to take over a collection -Before starting, ensure the collection is [abandoned]({{< relref "collections/reference/status#abandoned" >}}) or [terminated]({{< relref "collections/reference/status#terminated" >}}). +Before starting, ensure the collection is either [abandoned]({{< relref "collections/reference/status#abandoned" >}}) or [terminated]({{< relref "collections/reference/status#terminated" >}}). In any case, keep all original licenses, history, and attributions. ## Steps -1. If the approval is not explicitly given in the collection's README.md file, get it by contacting owners via email if publicly available, a GitHub issue on the collection repository or on the [community chat]({{< relref "federation/how-to/join" >}}). +1. If the approval is not explicitly given in the collection's README, get it by contacting owners via email if publicly available, a GitHub issue on the collection repository or on the [community chat]({{< relref "federation/how-to/join" >}}). -2. Ask the owner to transfer the repositories to your organization. +2. Ask the owners to transfer the repositories to your organization. -3. Verify that the declarations, snapshots and versions repositories are transferred and properly configured by taking a look at [this guide]({{< relref "/collections/how-to/create-repositories" >}}). +3. Check that the transferred declarations, snapshots and versions repositories are [properly configured]({{< relref "/collections/how-to/create-repositories" >}}). -4. Update the README.md file, and follow [this guide to update collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) inside the declarations repository. +4. Update the governance in the README files and in the [collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) in the declarations repository. -5. Follow [this guide to deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your server. +5. Set up continous integration and deployment is working to [deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your servers. -6. Ensure continous integration and deployment is working. - -Congratulations! You can now start maintaining the collection. - -Keep original licenses and attributions. +Congratulations and thanks! You are now officially maintaining the collection. diff --git a/content/collections/how-to/terminate.md b/content/collections/how-to/terminate.md index 0eb30bcd..a0ffc5a6 100644 --- a/content/collections/how-to/terminate.md +++ b/content/collections/how-to/terminate.md @@ -5,20 +5,18 @@ weight: 3 # How to terminate a collection -Follow these steps to properly terminate a collection you own, making it clear to users and potential successors that it is no longer actively maintained and can be taken over. +If you don't have the resources to maintain a collection anymore, follow these steps to properly terminate it. This will make it clear to users and potential successors that it is no longer actively maintained and can be taken over. ## Steps -1. Announce the intention to terminate the collection in the [community chat]({{< relref "/federation/how-to/join" >}}) to inform users and make potential new maintainers aware. Let some time, one month is recommended, for users to explicit their intenttion to take over the collection before proceeding to the next step. +1. Announce the intention to terminate the collection in the [community chat]({{< relref "/federation/how-to/join" >}}) to inform users and make potential new maintainers aware. Give at least one month notice to that others have time to share their intention to take over the collection before proceeding to the next step. If no-one has come forward after one month, you can proceed to the next step. -2. In the declarations repository's main `README.md` file, state that the collection is [terminated]({{< relref "collections/reference/status#terminated" >}}), encourage community to [take it over]({{< relref "collections/how-to/take-over" >}}). It can be done by adding the following snippet on the top of the file: +2. In the declarations repository's README, state that the collection is [terminated]({{< relref "collections/reference/status#terminated" >}}), encourage community to take it over. It can be done by adding the following snippet on the top of the file: -``` -This collection is no longer actively maintained. If you are interested in taking over maintenance, please let us know in the [community chat]({{< relref "/federation/how-to/join" >}}). -``` +> This collection is no longer actively maintained since ``. New maintainers are encouraged to take over the operation of this collection in order to resume tracking its terms. Guidance on [taking over maintenance]({{< relref "collections/how-to/take-over" >}}) can be found in the Open Terms Archive documentation, and help is available in the Open Terms Archive [community chat]({{< relref "/federation/how-to/join" >}}). -3. [Archive the collection's repositories](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) (declarations, snapshots, versions) to prevent further commits and signal the end of activity. +3. [Archive](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) the collection's repositories (declarations, snapshots, versions) to prevent further commits and signal the end of activity. -Once these steps are completed, the collection is officially terminated. It remains accessible but marked as inactive. +Congratulations, the collection is now officially terminated! Thank you for clearly labelling it as inactive while keeping its contents accessible and enabling others to continue your work. diff --git a/content/collections/reference/governance.md b/content/collections/reference/governance.md index 9739fc58..a53a1667 100644 --- a/content/collections/reference/governance.md +++ b/content/collections/reference/governance.md @@ -6,78 +6,77 @@ aliases: /collections/governance/ # Collection governance -Setting up and maintaining a collection needs fulfilling certain tasks. These tasks are handled through roles. Each of these roles can be volunteer or paid, and can be handled by one single or several different entities. The Open Terms Archive core team provides processes and tools to support all of these roles. +Setting up and maintaining a collection entails fulfilling specific tasks. These tasks are handled through roles. Each of these roles can be volunteer or paid, and can be handled by one or several different entities. -This reference documentation details all available roles that can be involved in a collection's governance to ensure its proper operation and maintenance. +This reference documentation details all roles that must be involved in a collection's governance to ensure its proper operation and maintenance. ## Roles -### `Host` +### Host -Ensures the foundational infrastructure required for the collection's operation is available. +Ensures the availability of the infrastructure required for the collection's operation. -**Responsibilities:** +#### Responsibilities - Provide the server infrastructure (self-hosted or rented). +- Apply hypervisor security updates if relevant. - Guarantee reliable internet connectivity for the server to fetch terms. --- -### `Administrator` +### Administrator Manages the technical operation of the collection's software, ensuring it runs smoothly, stays updated, and remains secure. -**Responsibilities:** +#### Responsibilities -- Keep the engine operational. -- Ensure terms are tracked. +- Ensure the engine runs at the specified schedule. - Ensure the public publishing of snapshots, versions, and datasets. -- Maintain and update the engine-related infrastructure. -- Apply necessary security patches to the infrastructure. +- Keep the engine and deployment systems up-to-date. +- Apply operating system security updates. --- -### `Curator` +### Curator Defines the collection's focus and ensures all included content aligns with that scope. -**Responsibilities:** +#### Responsibilities - Clearly define the collection's scope. - Make the collection scope publicly available via the metadata file. -- Verify that included services and terms adhere to the defined scope. +- Verify that included services and terms match the defined scope. --- -### `Maintainer` +### Maintainer Guarantees the integrity and quality of the collection's data by reviewing incoming contributions. -**Responsibilities:** +#### Responsibilities - Review contributions. -- Maintain the quality of tracked versions (e.g., removing noise, ensuring completeness). +- Maintain the quality of tracked versions (e.g. removing noise, ensuring completeness). --- -### `Contributor` +### Contributor -Actively adds new service information and keeps existing entries current. +Updates terms tracking and adds new entries. -**Responsibilities:** +#### Responsibilities - Add service declarations. - Keep service declarations up to date. --- -### `Sponsor` +### Sponsor -Provides essential non-operational support, such as funding or resources, to facilitate the collection's success. +Provides non-operational support such as funding or resources to facilitate the collection's success. -**Responsibilities:** +#### Responsibilities -- Provide funding for collection operations. -- Provide agent time for other roles. +- Provide funding or in-kind contributions for collection operations. - Provide political or institutional support. - Make other relevant non-operational contributions. diff --git a/content/collections/reference/status.md b/content/collections/reference/status.md index 2a8b9709..a06a67e3 100644 --- a/content/collections/reference/status.md +++ b/content/collections/reference/status.md @@ -5,38 +5,32 @@ weight: 5 # Collection status -This reference documentation outlines the different status levels that a collection can have within the system. Understanding these statuses is crucial for users to assess a collection's reliability, maintenance level, and current operational state. +This reference documentation outlines the different status levels that a collection can have within the system. Understanding these statuses is crucial for users to assess a collection's quality and reliability. -### `Active` +### Active -- The optimal operational state for a collection. - -- The collection maintains regular record saving with actively maintained and updated terms declarations. The number of tracked terms remains stable or increases over time. The tracking quality is high and stable. +The optimal operational state for a collection. +- The collection saves records regularly through actively maintained and updated terms declarations. The number of tracked terms remains stable or increases over time. The versions quality is high. - Technical maintenance includes regular dependency updates, access to the latest engine features, and benefits from all infrastructure updates. - -- All roles filled and active. +- All [roles]({{< relref "collections/reference/governance" >}}) are fulfilled. --- -### `Abandoned` - -- Collection may be functional but shows clear signs of neglect. +### Abandoned -- Operational status has deteriorated significantly with unknown record saving status, no updates to terms declarations, declining number of tracked terms, and decreasing tracking quality. +Collection may be functional but shows clear signs of neglect. +- Operational status has deteriorated significantly with unknown record saving status, no updates to terms declarations, declining number of tracked terms, and decreasing versions quality. - Technical maintenance has ceased completely, with no dependency updates, missing latest engine features, and no infrastructure updates. - -- All roles are inactive. +- All [roles]({{< relref "collections/reference/governance" >}}) are inactive. --- -### `Terminated` - -- Collection has ceased all operational activities. - -- Record saving is no longer active, though historical records remain accessible for reference purposes. +### Terminated -- No technical maintenance is performed as the collection is no longer operational. +Collection has voluntarily ceased all operational activities. -- No active roles exist as the collection is terminated. +- No terms are tracked anymore, though historical records remain accessible for reference purposes. +- No technical maintenance is performed. +- All [roles]({{< relref "collections/reference/governance" >}}) are inactive. From f220410137dd6efda206d78e556bae50afd829f3 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Thu, 10 Apr 2025 10:25:04 +0200 Subject: [PATCH 14/15] Fix whitespace --- content/terms/how-to/get-the-validUntil-date-from-an-issue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md index 5832e727..b24ae946 100644 --- a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md +++ b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md @@ -1,7 +1,7 @@ --- title: How to get the `validUntil` date linkTitle: Get the `validUntil` date -weight: 7 +weight: 7 --- # How to get the `validUntil` date From e62244c042209977c91502816eb39c1dd2625695 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Thu, 10 Apr 2025 10:41:03 +0200 Subject: [PATCH 15/15] Fix typo --- content/collections/how-to/take-over.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md index 38458db5..4e914ad7 100644 --- a/content/collections/how-to/take-over.md +++ b/content/collections/how-to/take-over.md @@ -17,6 +17,6 @@ Before starting, ensure the collection is either [abandoned]({{< relref "collect 4. Update the governance in the README files and in the [collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) in the declarations repository. -5. Set up continous integration and deployment is working to [deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your servers. +5. Set up continous integration and deployment to [deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your servers. Congratulations and thanks! You are now officially maintaining the collection.