DM-48013: Add contribution guide and pull request template

[JeremyMcCormick]

Added:

• Contribution guide at the standard location of CONTRIBUTING.md
• New pull request template with:
  • Checkbox for incrementing the schema version number, if applicable
  • Checkbox for referring to schema-specific information that may need to be consulted
• APDB documentation under docs/APDB.md, which includes versioning recommendations and other information relevant to contributing

It is planned to add more schema-specific documentation under docs for all major schemas, but probably not on this PR. Documentation for APDB is included here as a working case for which information to put in the main guide and what to put under the schema-specific pages.

---

The new contribution guide can be previewed here.

---

An APDB-specific schema versioning guide by @andy-slac which was used for the content in docs/APDB.md can be found here.

[JeremyMcCormick]

@kfindeisen I added a short section in the APDB docs mentioning that changes must be propagated to alert_packet. If you have specific language that you would like to include there, please let me know.

In terms of PR mechanics, does a merged PR on apdb.yaml trigger the updates to api_package, which could then come later? Or is this supposed to be done as a more-or-less simultaneous update to both repos?

[kfindeisen]

@kfindeisen I added a short section in the APDB docs mentioning that changes must be propagated to alert_packet. If you have specific language that you would like to include there, please let me know.

I have only a very rough knowledge of alert_packet; please direct those questions to @ebellm.

[andy-slac]

I think there is a lot of confusion about the role of the version numbers. I agree with Krzysztof that we should stop calling it SemVer. I think people used to think about version in terms of APIs, where "server" side can be updated before the "client" side (e.g. dynamic library is updated, which can cause rebuilding of the client apps). In our case the roles are reversed - we update sdm_schemas which is "immediately" picked up by the database client code, and only later we can decide to upgrade the actual database schema.

One more thing that I believe is implied in your description of schema compatibility is that the database schema version should be tracked somewhere (in the database itself), but there is no explicit mentioning of that anywhere.

[JeremyMcCormick]

@andy-slac

I agree with Krzysztof that we should stop calling it SemVer.

Based on this feedback, I reworded this section and removed the part about using using semantic versioning. Please have a look at the updated text.

we update sdm_schemas which is "immediately" picked up by the database client code, and only later we can decide to upgrade the actual database schema

I'm still not sure if this is a general case or APDB-specific. I'm going to make the main contributing text more agnostic about it.

the database schema version should be tracked somewhere (in the database itself), but there is no explicit mentioning of that anywhere

I plan to add this capability - see DM-47340.

[JeremyMcCormick]

@kfindeisen

Thank you for the thorough review!

I think this needs more coordination (with @andy-slac?) over what changes actually cause breakages. In particular, the primary table of examples assumes that DBs always use the latest schema, which in my experience is not true (migration support is often a low priority).

After discussing and reading through comments, I have realized that using an updated client on an older schema version is a more typical case than the reverse, so I will rewrite the main versioning "operations" table accordingly.

I also found quite a few typos and broken links, but I don't expect any controversy there.

The ones you mentioned should all be fixed now. Please let me know if you find additional mistakes.

[JeremyMcCormick]

w.r.t.

In particular, the primary table of examples assumes that DBs always use the latest schema, which in my experience is not true (migration support is often a low priority).

and

I think people used to think about version in terms of APIs, where "server" side can be updated before the "client" side (e.g. dynamic library is updated, which can cause rebuilding of the client apps). In our case the roles are reversed - we update sdm_schemas which is "immediately" picked up by the database client code, and only later we can decide to upgrade the actual database schema.

I don't think we can assume this as a general use case, as some other schema owners are considering it from the other direction.

I have made the main contributing guide a lot more generic, assuming that the schema subpages will outline their own versioning guidelines. I have also removed the table from CONTRIBUITNG which was providing suggestions for specific operations like removing or adding a column.

[kfindeisen]

Looks much better, thanks! Just minor comments.

[andy-slac]

Looks good, few suggestions.

[gpdf]

Looks good now. Don't wait for schema-specific documentation for ConsDB, but let's make sure there's a ticket for adding that.