Skip to content

Update contributing guidelines to mention backwards compatibilty #447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 21, 2025
Merged

Update contributing guidelines to mention backwards compatibilty #447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd678f6
Update contributing guidelines for backwards compatibility.
gouttegd May 21, 2025
44650c7
Fix broken link.
gouttegd May 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
19 changes: 18 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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:
Expand Down