Overview

In this module, we will describe the workflow that developers use to propose and approve changes in schemas in a standardized, governed process.

Schema proposals

Typically, we would use our Git repository and our standard review process to ensure that changes are aligned and agreed to. But we have a limitation with Git in this scenario: since our supergraph schema is composed of subgraph schemas, the supergraph schema does not actually live in Git, it's created when we publish a changed subgraph to GraphOS.

GraphOS schema proposals lets us:

• Propose changes to our subgraphs based on new desired functionality
• See the overall impact those changes will have on our supergraph
• Let graph stakeholders (client developers, domain teams, graph stewards) review proposed changes in the context of the whole supergraph
• Ensure that proposed changes will not break our existing graph or its current usage
• Ensure all schema updates are proposed, reviewed, and approved before publishing.

Let's try it out to see if we can propose changes to our Order type. Before we can create a proposal, we'll first need to configure it for our graph.

Configure schema proposals

1. Go to ➡️ Settings ➡️ This Graph ➡️ Proposals.

   https://studio.apollographql.com

   

2. Here, we can explore some options:

   • Set a minimum number of required approvers,
   • Assign default reviewers for this graph,
   • Adjust permissions for who can create and update proposals.

3. For our proposal trial, set the required approvers to 1.

   https://studio.apollographql.com

   

4. For demo purposes, we'll review our own proposal. (In the real world, you probably want others to do the reviewing!) Let's set ourselves as a default reviewer. Select the Manage Default Reviewers button and choose your name as the default reviewer.

   https://studio.apollographql.com

   

5. Click the checkbox to "Require at least 1 default reviewer for all proposals on this graph".

   https://studio.apollographql.com

   

6. We also want to add proposals to our checks setup. This will allow GraphOS to verify that any proposed schema changes have been reviewed as part of a proposal. Under the Proposal implementation section, set the dropdown to Error.

   https://studio.apollographql.com

   

Create a proposal

Now that we're configured our proposals, it's time to create one!

For this proposal, the Order type lacks some key details that would be valuable to have at that level. In particular, adding the order cost and date would make our Order type more complete for our clients!

1. Navigate to the Proposals tab and select Propose changes:

1. In the modal, we'll set the following values:

   • Proposal title: Enhance Order entity
   • Why are you creating this proposal?: Our client teams requested total cost and order date to be included in the order entity.
   https://studio.apollographql.com

   

2. Click Create Proposal.

3. In the next page, let's select the orders subgraph schema and add two new types to the Order entity. Find the Order type in the file and add the field definitions along with descriptions.

   """
   The total cost of the order
   """
   total: Float
   
   """
   The date the order was made
   """
   orderDate: String

   Copy

   This code adds a total field of type Float and an orderDate field of type String.

4. Click the Save Revision button in the bottom-left corner of the screen.

   https://studio.apollographql.com

   

   That's it!

Schema proposal checks

1. Navigate to the Checks tab of the proposal. We can see here that our proposal workflow automatically ran schema checks against our proposal, and that our proposed changes compose successfully and do not break any existing usage against our existing graph.

   https://studio.apollographql.com

   

Opening a proposal for review

Great, we now have a proposal that's safe to add to our supergraph. It's time to open it for review.

1. Head over to the Overview tab to begin the review process.

2. Click the Edit status button on the right-hand side.

3. Change the status to Open for feedback.

   https://studio.apollographql.com

   

Review a proposal

You should automatically be assigned as the reviewer.

1. Navigate to the Changes tab to view the modifications. Here, you can see a diff of the changes to our graph.

   https://studio.apollographql.com

   

2. Let's comment on these changes. To start, click on the chat icon beside the line for orderDate, which will show up when you hover over the changes. This will open the comment view where we can add our comments.

3. In the comments section, add a comment that says "Looks good to me!" and click the Comment button.

   https://studio.apollographql.com

   

Approve a proposal

We have looked at the changes, made comments and we're happy with the changes. It's time to approve the proposal.

1. Navigate to the Overview tab at the top, and then click the Add Review button:

   https://studio.apollographql.com

   

2. Select the Approve proposal checkbox then click on Add review.

   https://studio.apollographql.com

   

   Now that the review has been approved by one reviewer, the proposal will change state to approved.

Implement the proposal

Now that the proposal has been officially approved, these changes are ready to be implemented. Head back to GitHub and we can add these changes into our schema.

1. In GitHub, open up the orders-schema.graphql file and click on the ✏️ pencil edit icon in the upper right corner to start editing the file.

   https://github.com

   

2. Now we want to add the schema changes from the proposal. In a normal workflow, you could export your changes from the proposal leveraging Apollo's CLI, rover. In this case, since we are doing our development in GitHub directly, we can just manually add the changes from the proposal.

   Add the following code to the end of the Order type (line 30):

   """
   The total cost of the order
   """
   orderTotal: Float
   
   """
   The date the oder was made
   """
   orderDate: String

   Copy
   https://github.com

   

3. Commit your changes.

Note: You may have noticed that the name of the total field from the initial proposal has been changed to orderTotal. We have purposely introduced this so we can then see the results of the check process against this change. We will fix this later!

Check your work

1. Head back to Studio and go to the Checks page. Uh-oh, our changes were not successful!

   https://studio.apollographql.com

   

2. Click on the failed task to see the details of the failed proposals check.

   The issue is that our changes did not match our proposal. The code we added had the wrong name for the order total. Our proposal has a name of total but our submission used orderTotal.

   https://studio.apollographql.com

   

3. Let's fix this in GitHub and try again. Head back to our repository and open up the orders-schema.graphql file by clicking the ✏️ pencil button in the upper right corner again.

4. In the edit pane, change the name of orderTotal to total.

   https://github.com

   

5. Commit the changes.

6. Head back to Checks in Studio. The workflow should now have passed:

   https://studio.apollographql.com

   

7. Click on the successful check run and select Proposals. We can see the proposal that our changes mapped to:

   https://studio.apollographql.com

   

8. Click on that proposal. We can see that it's now marked as IMPLEMENTED:

   https://studio.apollographql.com

   

And with that, we have used the schema proposals feature to take a supergraph schema from ideation to implementation.

Up Next

We've learned a ton on how we can use schema proposals to provide us a standardized approach to collaborate on schema changes, but what happens if we need to move fields across different subgraphs? The next section will teach us how we can incrementally roll over fields to different subgraphs.