Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Propose Schema Changes

Edit schemas, lint and check changes, and request reviews in GraphOS


This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.

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

Proposal creation
Start proposal
Draft status
Edit subgraphs, lint,
save, and check changes
Request reviews

Start a proposal

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

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 , select a source variant. The '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 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 from a proposal's Editor tab.

Schema proposals editor in GraphOS Studio

To start a new , click +Add new from the selector in the left navigation. You can also delete existing subgraphs and rename newly created ones by clicking the ••• menu to the right of a subgraph's name.

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.

Highlighting linting violations in GraphOS Studio

NOTE

A violation line number may no longer exist because you've renamed or deleted a . When this happens, the violation appears grayed out in the violations list.

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.

💡 TIP

You can think of each revision as equal to a commit in the version control paradigm. Making each revision an atomic change can give reviewers an overview of the changes that make up a proposal.

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.

NOTE

Schema proposals—even approved ones—don't deploy any changes to your graph. Once a proposal is approved, your team must implement and publish the changes.

Previous
Configure Proposals
Next
Review Proposals
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company