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.
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.
Step 3 - Edit the page
Use Github’s integrated editor to make the changes you plan on submitting.
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.
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
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.
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