Define and Document Breaking Changes Policy for WPGraphQL

josephfusco commented 4 months ago

Overview

As a WPGraphQL maintainer, I would like a knowledge base of upgrade guides for breaking changes in order to ensure smooth transitions. This will provide clear, step-by-step instructions for users to upgrade without issues, minimizing downtime and frustrations.

As a WPGraphQL maintainer, I would like to define a breaking change policy, defining the following:

High Impact (e.g. breaking schema)
Medium Impact
Low Impact

Acceptance Criteria

[ ] Blog post announcing future breaking changes
[ ] Markdown file in repo explaining future breaking changes
[ ] Initial email sent to WPGraphQL's ~30k subscribers announcing future breaking changes (reference blog post)

Links

For inspiration:

https://laravel.com/docs/9.x/upgrade

justlevine commented 4 months ago

@josephfusco is the goal of this to define a check list of requirements for accompanying documentation around a breaking release (my understanding of the overview) or to create specific Documentation regarding a specific upcoming breaking release (the acceptance criteria)?

jasonbahl commented 4 months ago

@justlevine we kinda created this issue as a placeholder from a verbal discussion we had.

Basically the goal here is to help calm some of the fears I have around releasing breaking changes when we decide we need to finally do it (i.e. the php version and graphql-php version bumps, and any other future breaking changes)

I want to work on a document that can communicate to the community what process(es) we will follow when we have a breaking change release, how we will communicate the breaking changes (i.e. categorized as High, Medium, Low impact), how we will document the upgrade paths, etc, etc.

Then, I would like to figure out how to process-ify this to ensure I/we follow the process if/when we need to make such releases.

As you know, I've made some breaking change releases in the past that probably should have been semver major updates, but I justified them as bugfixes, largely because I'm scared of what will happen when we have a split in the ecosystem between 1. and 2., etc.

I have a fear that when we release a 2.0 version, the community will split and we'll have folks that are on 1. and folks on 2. and support, maintenance, etc will become increasingly difficult for core WPGraphQL, extensions, consumers (i.e. Faust, etc).

If we can set the precedent and properly communicate to the community that major releases will be major in the semver sense and not major in the "we re-architected the entire plugin" sense, then I think we can help the community move forward on the latest versions without the split I'm fearful of.

I think in the WordPress ecosystem a 2.0 of a plugin has typically been a huge refactor and not just a minor technical breaking change.

I would love to get to a point where we can make breaking releases that users can upgrade to in minutes vs hours or days. Like I don't want to pile up 43 breaking changes then release a 2.0 that takes a user 2 weeks to rebuild their projects to be compatible with. I would love to release breaking changes (when necessary) that took users 30 seconds to upgrade to be compatible with, if they are even impacted by said change.

For example, release v1.13.0 realistically should have been a semver major release. Because of my fears (i.e. ecosystem split, etc) I justified in my mind that this didn't justify a major, and I released it as a minor.

I would love to get to a point where I could release something like this as a semver major and help the community understand that "major" simply means what semver intends it to mean "something in this release is considered breaking" and not what the WordPress community typically means with a major (i.e. the entire plugin is different)

I would like to solidify a process for how we communicate the severity/impact/estimated time to update, of breaking changes so users can be more educated on when it makes sense to upgrade vs hold off, etc.

There will be times where we release a breaking change, like v1.13.0 where the impact is so low that most users won't even notice anything changed and don't need to take any action to remain compatible.

Then there will be releases, like the graphql-php version bump that might impact a wider audience and might require some action from some users.

Then there will be releases where nearly everyone is impacted but the time to update is minimal (i.e. if we decided we NEEDED to change a field in the schema or a function/hook/filter signature or something)

Then, there will also likely be releases where the time to update might require more time.

I want to be able to set a standard for how we communicate these things, how we document them, etc. . .and then processify it so I and other contributors can help follow the "policy".

This is probably a lot of rambling but hopefully it communicates my fears and what we're trying to solve here. I think a lot of it comes down to communication with the community, updating docs and processes, etc. It's probably more about helping me overcome some of my fears as a maintainer more than anything else.

wp-graphql / wp-graphql