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 new file mode 100644 index 00000000..4e914ad7 --- /dev/null +++ b/content/collections/how-to/take-over.md @@ -0,0 +1,22 @@ +--- +title: Take over a collection +weight: 4 +--- + +# How to take over a collection + +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, 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 owners to transfer the repositories to your organization. + +3. Check that the transferred declarations, snapshots and versions repositories are [properly configured]({{< relref "/collections/how-to/create-repositories" >}}). + +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 to [deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your servers. + +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 new file mode 100644 index 00000000..a0ffc5a6 --- /dev/null +++ b/content/collections/how-to/terminate.md @@ -0,0 +1,22 @@ +--- +title: Terminate a collection +weight: 3 +--- + +# How to terminate a collection + +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. 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 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 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](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. + +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/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 1019b9a7..a53a1667 100644 --- a/content/collections/reference/governance.md +++ b/content/collections/reference/governance.md @@ -1,35 +1,82 @@ --- title: Governance -weight: 4 +weight: 1 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 -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. +Ensures the availability of the infrastructure required for the collection's operation. + +#### 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 -This role takes responsibility for ensuring that the engine and associated software tools are functional and up to date. +Manages the technical operation of the collection's software, ensuring it runs smoothly, stays updated, and remains secure. + +#### Responsibilities + +- Ensure the engine runs at the specified schedule. +- Ensure the public publishing of snapshots, versions, and datasets. +- Keep the engine and deployment systems up-to-date. +- Apply operating system security updates. + +--- ### Curator -This role decides which services and terms are welcome in the collection. +Defines the collection's focus and ensures all included content aligns with that scope. + +#### Responsibilities + +- Clearly define the collection's scope. +- Make the collection scope publicly available via the metadata file. +- Verify that included services and terms match the defined scope. + +--- ### Maintainer -This role guarantees the quality of the tracked versions by reviewing contributions. +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 -This role adds declarations and keeps them up to date. +Updates terms tracking and adds new entries. + +#### Responsibilities + +- Add service declarations. +- Keep service declarations up to date. + +--- ### Sponsor -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. +Provides non-operational support such as funding or resources to facilitate the collection's success. + +#### Responsibilities + +- 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/metadata.md b/content/collections/reference/metadata.md index 06a1191d..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/ --- @@ -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 diff --git a/content/collections/reference/status.md b/content/collections/reference/status.md new file mode 100644 index 00000000..a06a67e3 --- /dev/null +++ b/content/collections/reference/status.md @@ -0,0 +1,36 @@ +--- +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 quality and reliability. + +### Active + +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]({{< relref "collections/reference/governance" >}}) are fulfilled. + +--- + +### Abandoned + +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]({{< relref "collections/reference/governance" >}}) are inactive. + +--- + +### Terminated + +Collection has voluntarily ceased all operational activities. + +- 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. 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 --- 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..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,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