RFC: Repository -- Proposal for tracking schema changes

[macintoshpie]

This is a request for comments on how the developers of BuildingSync should manage future releases and report changes to users.

context

With the release of version 3.0, we now have two primary development branches of the schema. As we prepared to release 2.4 and 3.0 we came to realize how challenging it was becoming to keep track of items for the changelog. This is a proposal for keeping track of the changes to the schema (ie changelog)

proposal

• PRs should be our "source of truth" for important changes to the repo/schema
• We should encourage separate PRs for each "logical"/"discrete" change to the schema (especially if the changes are impactful/non-trivial to users)
• The base for the PR (e.g. develop (currently our 2.x branch) or develop-v3 (our 3.x branch), what we're merging into) indicates the schema we're affecting. This means the changes will go into that base's changelog, and any release made off of it will include those notes.
• The labels for the PR indicate the implications of the changes.
  • If a PR should be ignored in the changelog, it must include the ignore label. If a PR modifies the schema in any meaningful way it should not include this label. All non-ignored PRs must meet the remaining requirements.
  • Every PR must include a breaking change or non-breaking change label
  • Every PR should include at least one category (e.g. Controls, Documentation, General, etc)

examples

• A pull request from my-neat-feature into develop (currently our 2.x branch) would result in an update to the v2.x release notes and changelog.
• Example of a "negated" change: Person at time 1 made a breaking change (labeled breaking change) then at time 2 realized we didn't want it so made another PR. So after second PR was merged the changes were reverted. Both PRs should have the ignore label (and not include any other labels).

alternatives

• We could instead continue using issues to track changes. This is a bit messier however b/c we would need to label what version of BSync an issue is for. If an issue is for both versions, then the Breaking/non-breaking label might conflict, so we'd need two issues. Also I think there's a benefit to looking at
• We could just have repo maintainers update the CHANGELOG.md themselves on each PR. No need to label things/run a script to pull changes

[macintoshpie]

@nllong @JieXiong9119 @Ryoken thoughts on this process? We'd have to update our release script to be more "branch focused" if the proposed solution is the direction we'd like to go

[JieXiong9119]

Great! We could add some details for labeling like the following:

We have two sets of labels for change types (other than breaking change vs. nonbreaking change vs. ignore). One set tells where the change takes place in the schema, which includes

• Controls
• Documentation
• General
• Measures
• Reports
• Systems
• Validation
• Other

The other set of labels indicates the functions of the change, which includes

• feature (new function)
• enhancement (improved function)
• bug (fix)

I don't know the original idea but I think it's best for a PR to select at least one label from each set to have a clear and full preview. There are other labels related to specific use case or project (e.g. STD 211 Mapping, CTS-support). Some labels are vague to me such as duplicate, and I suggest we delete it if useless.

[nllong]

This process sounds good. I like that PRs are the items that are tracked in the change logs. And I do think that there will be a mix of manual edits to the changelog and automated generation.

Jie's comment is spot on in that we need to make sure that we label the PRs accordingly. duplicate was there to allow for an issue to be redundant and noted as such. Not sure duplicate makes sense when dealing with PRs.

[macintoshpie]

Sounds good, I will formalize this in the repo docs. I'll add Jie's notes on the category labels