Propose Schema Changes

This article describes actions in the Proposal creation stage of the schema proposal workflow.

Start a proposal

You can create a new proposal in GraphOS Studio from a graph's proposals page. To access the page, either:

• Open the Proposals page from the left navigation from a particular graph.

  
  note

  If you don't see Proposals in the left navigation of a particular graph, it may be because the graph is a monograph. Schema proposals are designed for use with supergraphs and aren't available for monographs. Convert your monograph to a supergraph using the Rover CLI subgraph publish command with the --convert flag.

• On the Graphs page, click the pencil icon with the tooltip that says Go to schema change proposals for a particular graph.

  

Follow the steps below to create a new proposal:

1. Click the Propose changes button in the top right. A dialog entitled Propose schema changes appears.

2. Enter a descriptive proposal title that outlines the schema changes you plan to propose.

   note

   If you want to edit the proposal's title later, you can do so from its Overview tab.

3. If you've started the proposal from a graph rather than a particular variant, select a source variant. The source variant's schema is used to start the proposal, but the proposal isn't kept in sync with any schema changes that occur while the proposal is in progress.

   tip

   Apollo recommends creating schema proposals from development variants.Proposing schema changes from a development variant minimizes the risks associated with making direct changes to a production schema. It allows for the earliest detection of issues and potential improvements.
   note

   You can't create proposals for contract variants since these are automatically generated based on their source variant.

4. Optionally, enter the rationale for the proposed changes. This rationale appears as your proposal's Description on the proposal's overview and gives collaborators and reviewers context for the proposed changes. This input accepts Markdown.

   note

   If you want to edit the proposal's description later, you can do so from its Overview tab.

5. Click Create Proposal.

Once you've created the proposal, you land on the newly created proposal's Editor tab. This tab is where you make the schema changes you want to propose.

Edit subgraph schemas

You can directly edit one or more subgraph schemas from a proposal's Editor tab.

The proposals editor provides features like autocomplete, hovering over types and directives for more information, and syntax and schema validation.

The editor also lets you run composition on your proposed changes to uncover composition errors before you finalize your proposal. To run composition, click the icon with three boxes in the top right of the editor. Next to the button, you can toggle on Compose on change so that composition automatically runs on every change.

Lint changes

To lint the schema changes you've made, click the broom icon in the top right of the editor. Clicking the button opens a panel where you can run the schema linter on the current changes in the editor. After successfully running a lint on your schema, the panel displays any linter violations so you can fix them accordingly.

If you are having trouble finding the exact location of where the lint violation occurred, click the line in the violations list to highlight it in the editor.

Once you've made changes in the editor, rerun the linter by clicking the rerun button in the top right of the schema linting panel.

Save revisions

Once you've made changes, click the Save Revision button in the bottom left of the editor to save them. A dialog appears where you can optionally include a summary of your changes. This input accepts Markdown.

The revision summary appears in the activity your proposal's overview tab. A proposal can include as many revisions as necessary.

Schema checks

Schema checks automatically run each time you save a revision. These appear in a proposal's Checks tab.

Checks run proposal changes against the most recent version of the proposal's source variant schema. For example, if your proposal removes a field that was already removed in the latest published version of the source variant, the check doesn't consider the removal a change. This allows checks to detect breaking changes in the proposal as efficiently as possible.

Self-review and commentary

While working on a proposal and before requesting reviews from teammates, you may want to review the proposal yourself. See the Review proposals article for how to review different aspects of a proposal and provide commentary on it.

Change proposal status

You can change the proposal's status from the overview page by clicking Edit status. You have the following options:

• Draft: default status upon creation

• Open for feedback: signals the proposal is ready for review

• Closed: signals the proposal is abandoned or suspended

  • Closed proposals can't receive further revisions

  • You can always reopen a proposal by resetting the status to Draft or Open for feedback

Approved and Implemented statuses are automatically set once necessary conditions have been met.

Request review

Add reviewers by clicking Manage reviewers on the proposal's overview tab. If proposals have default reviewers configured, these are automatically selected once the proposal's status is Open for feedback.

Approvals

Once a proposal receives the minimum number of approvals, its status changes to Approved.

Revisions made to an approved proposal don't change the Approved status of the proposal. To set the proposal's status to Open for feedback or another status, manually change it from the proposal's overview page.

Once a proposal is approved, your team can begin implementing the approved changes.