From 081515ab33304305ec21c474959006d77a6f5bae Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 9 Dec 2024 15:13:48 -0600 Subject: [PATCH] Add contribution guide --- CONTRIBUTING.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..70bbaa38 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,50 @@ +Contributing to SDM Schemas +=========================== + +Creating a PR +------------- + +All changes to the repository must be made by [opening a pull request](https://github.com/lsst/sdm_schemas/compare), which will require one approving reviewer. Any branches used for PRs which contain non-trivial changes should follow the [standard DM naming convention for ticket branches](https://developer.lsst.io/work/flow.html#ticket-branches), or the PR will be rejected and closed. + +The PR title should be formatted like: `[TICKET]: [TITLE]` where `TICKET` is the Jira ticket and `TITLE` is a short description. + +For example, this is a valid PR title, using a dummy ticket number: + +`DM-12345: Add ra and dec columns to test schema`. + +Including the name of the schema in the PR title is also helpful, e.g., `test` in this case. + +The description body of the PR should contain clear information on what is being changed in the schema, though this may be fairly brief. +A set of bullet points describing each change will usually suffice. +The Jira ticket page can be used as a source of extended information on the issue being resolved. + +An appropriate reviewer should be assigned, based on which schema is being changed or added. If the author does not know who should review their PR, [JeremyMcCormick](https://github.com/JeremyMcCormick) can be assigned as a default, and an appropriate reviewer will be found. + +The author should [resolve the review](https://developer.lsst.io/work/flow.html#resolving-a-review) if changes are requested. Once the PR is approved, it may then be merged by the author. + +Schema Versioning +----------------- + +Individual schemas may have their own internal [version](https://felis.lsst.io/user-guide/model.html#schema-version) for tracking changes, which is defined at the top level of the file, as in [apdb.yaml](yml/apdb.yaml). +(This is distinct from tags or versions of sdm_schemas itself, and not all schemas may be using these internal versions.) +This version may need to be updated when making changes. + +Usage of semantic versioning is recommended, which defines a version like `MAJOR.MINOR.PATCH`, such as `1.2.3`. + +The following generic guidelines can be used for this versioning scheme: + +- `MAJOR`: Breaking changes that are not backward compatible. +- `MINOR`: Backward-compatible changes. +- `PATCH`: Backward-compatible changes, typically those that do not change the database schema. + +Exactly how these versions are used and incremented is typically schema-dependent, and the [specific schema documentation](#specific-schema-documentation) should be consulted for those rules and guidelines. + +Database Migration +------------------ + +Database migrations are currently performed with schema-specific tooling in external repositories, so documentation for that particular schema should be consulted on how to perform them and how this may impact the pull request process. + +Specific Schema Documentation +----------------------------- + +- [Alert Production Database (APDB)](docs/APDB.md)