From bd678f6c48eaed3761d8b8eb4a232ce472b54057 Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Wed, 21 May 2025 17:37:13 +0100 Subject: [PATCH 1/2] Update contributing guidelines for backwards compatibility. Add a section to the CONTRIBUTING.md file to remind would-be contributors of the need to consider backwards compatibility, and to show how new slots should be tagged with the version of the spec they are introduced with. Also add a checkbox to the pull request template to remind contributors that new slots should be tagged as such. --- .github/pull_request_template.md | 1 + CONTRIBUTING.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7194eb17..4e954fe4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,6 +10,7 @@ If you are proposing a change to the SSSOM metadata model, you must - [ ] provide a full, working and valid example in `examples/` - [ ] provide a link to the related GitHub issue in the `see_also` field of the linkml model - [ ] provide a link to a valid example in the `see_also` field of the linkml model +- [ ] make sure any new slot is annotated with the appropriate `added_in` annotation - [ ] run SSSOM-Py test suite against the updated model diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f330b8e4..c1965599 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,6 +84,23 @@ Unsure where to begin contributing to SSSOM? You can start by looking through th * [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two. * [Help wanted issues][help-wanted] - issues which should be a bit more involved than `beginner` issues. +### Considerations when proposing changes to the model + +Now that SSSOM 1.0 has been released, and until we start working on a hypothetical SSSOM 2.0, any proposed change to the SSSOM model must consider the issue of backwards compatibility. + +The key point is that _a set that is compliant with version 1.0 of the specification must be usable “as is” with an implementation compliant with any 1.x version_. + +This is automatically achieved if all the proposed changes do is _adding_ new _optional_ slots, or _new_ enumeration values. For that reason, it is strongly recommended that evolution of the 1.x branch be limited to this type of changes only, and that other changes be reserved for a hypothetical version 2.0. + +In addition, new slots must be marked with a `added_in` annotation indicating the version in which the slot will be introduced, as in the following example: + +```yaml +my_new_slot: + instantiates: sssom:Versionable + annotations: + added_in: "1.1" +``` + ### Pull Requests The process described here has several goals: From 44650c7625037f372038930316f57b5f5b1167bb Mon Sep 17 00:00:00 2001 From: Damien Goutte-Gattat Date: Wed, 21 May 2025 17:39:28 +0100 Subject: [PATCH 2/2] Fix broken link. The "overview" page had been moved quite a while ago, point to the "introduction" instead. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1965599..31c4ed62 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ We have an official message board with a detailed FAQ and where the community ch ## What should I know before I get started? -- Read the [overview](https://mapping-commons.github.io/sssom/spec/) +- Read the [introduction](https://mapping-commons.github.io/sssom/introduction/) - Do the [SSSOM tutorial](https://mapping-commons.github.io/sssom/tutorial/) - Read about the [SSSOM toolkit](https://mapping-commons.github.io/sssom-py), which is managed [in a different repo](https://github.com/mapping-commons/sssom-py)