Enhance CONTRIBUTING.md with change control details

[tghosth]

Added detailed change control and release process guidelines.

[tghosth]

@elarlang please can you just confirm you agree with all the content here as this basically sets our policy for upcoming ASVS changes

[narfbg]

I'm noticing a couple of things ...

The tags are confusing or at least not explained well upfront. There's a natural conflict with the specific meaning of "tags" in Git, and GitHub issue labels can be thought of as tags as well.

Having to manually reverse breaking changes as a core part of the process seems error-prone and primitive as a solution. Why not just use proper git branches instead?

That would also go a long way to remove friction for changes that have to wait for a major version. Currently, any changes that don't qualify for minor/patch have to wait indefinitely with no progress beyond a discussion that would get put on hold. This discourages contributions (in multiple ways), creates a larger workload before major releases, and in the meantime ideas, thoughts, and details get lost in time.

[tghosth]

The tags are confusing or at least not explained well upfront. There's a natural conflict with the specific meaning of "tags" in Git, and GitHub issue labels can be thought of as tags as well.

Perhaps but this is the terminology we used in the run up to v5.0.0 so it is understood within the project.

Having to manually reverse breaking changes as a core part of the process seems error-prone and primitive as a solution. Why not just use proper git branches instead?

Because we would then have to manually maintain multiple branches in parallel which is super painful. E.g., if we want to make patch level change we have to make it in parallel in 3 places. Cherrypicking would not necessarilly if things have moved around in the "major change" branch.

That would also go a long way to remove friction for changes that have to wait for a major version. Currently, any changes that don't qualify for minor/patch have to wait indefinitely with no progress beyond a discussion that would get put on hold. This discourages contributions (in multiple ways), creates a larger workload before major releases, and in the meantime ideas, thoughts, and details get lost in time.

By allowing "minor" changes, this covers the vast majority of possible change types.

[narfbg]

Right, I assumed the tags usage is an established practice that you're already comfortable with. But it could use a better explanation in a contribution guide ... Minor wording improvement should suffice, even just saying "inline tags".

That would also go a long way to remove friction for changes that have to wait for a major version. Currently, any changes that don't qualify for minor/patch have to wait indefinitely with no progress beyond a discussion that would get put on hold. This discourages contributions (in multiple ways), creates a larger workload before major releases, and in the meantime ideas, thoughts, and details get lost in time.

By allowing "minor" changes, this covers the vast majority of possible change types.

Isn't that a self-fulfilling prophecy? :)
All breaking changes are major changes, and those get delayed indefinitely - both by convention and by desire to keep things tidy by not making many changes - so only relatively minor changes are allowed. When a new contributor comes in, they see this, and know that their breaking-change proposal can't be finalized anytime soon, so they question if it's worth even opening an issue.

The process itself discourages major changes, but there's hardly evidence that this serves a natural order of sorts. I'm honestly not sure how most changes wouldn't technically qualify as major in a rule-enforcing standard, since almost all normative changes are breaking by definition.

I skipped replying to your other paragraph because this (not letting major changes stall in discussion threads) is a more compelling argument for git branching.

[tghosth]

Right, I assumed the tags usage is an established practice that you're already comfortable with. But it could use a better explanation in a contribution guide ... Minor wording improvement should suffice, even just saying "inline tags".

That would also go a long way to remove friction for changes that have to wait for a major version. Currently, any changes that don't qualify for minor/patch have to wait indefinitely with no progress beyond a discussion that would get put on hold. This discourages contributions (in multiple ways), creates a larger workload before major releases, and in the meantime ideas, thoughts, and details get lost in time.

By allowing "minor" changes, this covers the vast majority of possible change types.

Isn't that a self-fulfilling prophecy? :) All breaking changes are major changes, and those get delayed indefinitely - both by convention and by desire to keep things tidy by not making many changes - so only relatively minor changes are allowed. When a new contributor comes in, they see this, and know that their breaking-change proposal can't be finalized anytime soon, so they question if it's worth even opening an issue.

The process itself discourages major changes, but there's hardly evidence that this serves a natural order of sorts. I'm honestly not sure how most changes wouldn't technically qualify as major in a rule-enforcing standard, since almost all normative changes are breaking by definition.

I skipped replying to your other paragraph because this (not letting major changes stall in discussion threads) is a more compelling argument for git branching.

The only changes considered "major" are those which move requirements about or which create new sections. The "minor" changes allow all sorts of other requirement manipulations including strengthening, weakening, deleting, merging, splitting and transforming.

[elarlang]

@narfbg - I think you can just read or interpret those tags as "some weird noise for leaders to track changes".

Those tags are something that leaders need to take care of and track.

We did a similar procedure from v4.0 to v5.0, and based on that, we can provide mapping, see https://asvs.dev/Mappings/

[narfbg]

I'm familiar with them, that wasn't for my benefit. :)