How to Propose a Change

The Astro User Experience Design System is hosted on GitHub as an open source project and uses Markdown for content. This enables any user of Astro to proposes changes in a safe, trackable and relatively easy manner.

You will need a free GitHub account to propose changes to Astro.

If you are new to Git and Git fork workflows the easiest way to edit Astro content is through GitHub’s online interface. If you are comfortable with Git and forking repositories skip to Step 5 below to see information about creating a pull request.

Step 1 - Navigate to the page you want to edit

At the bottom of each page on AstroUXDS.com you will find a link titled Propose a change or fix to this page. Follow the link to propose your change on GitHub. If you are not an authorized Astro contributor you will be asked to create a fork of the repository, this is a safe operation. You cannot break Astro proposing a change.

Step 2 - Fork the Astro repository

If you aren’t a member of the Astro team your proposed changes use Git’s fork process. This effectively creates an identical clone of Astro you can edit without affecting the published version.

GitHub’s integrated Markdown editor
GitHub’s integrated Markdown editor

Step 3 - Edit the page

Use Github’s integrated editor to make the changes you plan on submitting.

GitHub’s integrated Markdown editor
GitHub’s integrated Markdown editor

Step 4 - Propose change

When you have completed your changes scroll the browser window down to the Propose file change interface at the bottom of the page.

Create a brief description of the change you are proposing in the first field. This is required. Keep this description informative but succinct. If your change requires more than a brief length of text use the larger text field to elaborate on your change.

Click the Propose file change button

This is a commit message and will be forever included in the Astro changelog.

GitHub’s integrated Markdown editor
GitHub’s integrated Markdown editor

Step 5 - Confirm your changes and create a pull request

Take a moment after submitting your change to confirm there are no errors. GitHub will present the file you are changing, the previous version highlighted in red and your proposed change highlighted in green.

When you are satsified your change is ready for review click the Create pull request

The pull request screen will auto-populate the text field with your previous commit message(s). Feel free to leave these as your pull request or if you think your change needs additional clarification enter that now.

NOTE: Once you click Create pull request all your changes, commit messages and pull requests become public and part of the permanent Astro record

Once you are content with your changes click Create pull request

GitHub’s integrated Markdown editor
GitHub’s integrated Markdown editor

Step 6 - Preview your change

Every pull request on AstroUXDS gets published to its own ephemeral URL for testing. You can view your changes live by clicking the Details link associated with the final check, deploy/netlify - Deploy preview ready! This URL is valid for as long as the pull request is open and will automatically delete itself after the pull request is closed or merged in to Astro.

Don’t worry about the two red error messages, these are simply safeguards preventing changes being made public prior to necessary approval
Don’t worry about the two red error messages, these are simply safeguards preventing changes being made public prior to necessary approval

Step 7 - Approval process

The Astro team reviews pull requests weekly. Proposals may be

  • Implemented immediately in a "minor" release version
  • Scheduled for implementation in a future release if the scope of change requires sufficient effort
  • Returned with requests for further clarification or guidance on changes necessary for acceptance
  • Rejected if the proposal is not suitable for Astro at this time