Contributing to Well-Architected Labs
- Nathan Besh. Cost-Lead, Well-Architected, AWS
- Alee Whitman, Commercial Architect (AWS OPTICS)
The Well-Architected labs are open source and we welcome feedback and contributions from the community.
Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.
If there are errors or you wish to make improvements to the labs, you can perform a pull request. To create a pull request, follow the steps below.
Reporting Bugs/Feature Request
We welcome you to use the GitHub issue tracker to report bugs or suggest features.
When filing an issue, please check existing open
or recently closed
issues to make sure somebody else hasn’t already
reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
- A label with the Well-Architected framework pillar (i.e. COST)
- A reproducible test case or series of steps
- The version of our code being used
- Any modifications you’ve made relevant to the bug
- Anything unusual about your environment or deployment
Contributing via Pull Requests
Process for updating any existing labs or creating a new lab
- You check existing open, and recently merged, pull requests to make sure someone else hasn’t addressed the problem already.
- You open an issue to discuss any significant work or new lab ideas - we would hate for your time to be wasted.
- GitHub account
- Git setup locally on your PC
- Install Hugo
Create a fork
You will create a fork to work on, make the edits and then submit it to be merged back into production. A local fork will be your local copy of the Well-Architected Labs repository.
- Go to the production Well-Architected Labs repository
- On the right side of the page, click on the Fork icon
- Select your GitHub account to fork to
- You will then have a remote repository of /aws-well-architected-labs
This is effectively your own version of the labs, stored on GitHub
Create a local repository from the fork
You will create a local copy of the fork to work on, and make the required edits, his allows you to work locally and view the changes.
- Create a directory on your PC to hold the local repository
- Change to that directory or navigate to that directory and right click and select Git Bash Here
- Replace the repository name (username)/aws-well-architected-labs below with your repository name, and clone it:
git clone firstname.lastname@example.org:(username)/aws-well-architected-labs.git
- It will download the repository
- You now have your local copy setup & have your own GitHub repository to push to
Make changes or create new content
Note: Modify the source. Please focus on the specific change you are contributing. If you make modifications to multiple labs please submit a separate request for each lab.
Make changes on an existing lab
Click here for the steps to make changes on an existing lab
Create a new lab
Click here for the process to create a new lab
Verify your edits and/or additions
After making the changes or additions test and verify locally
Navigate back to the aws-well-architected-labs parent folder
Serve the content locally:
hugo serve -D
Open a browser and navigate to http://localhost:1313/
Verify the change you made was correct and there were no problems introduced
Push your changes to the remote repository:
Push your changes to GitHub, so that they are stored and backed up by GitHub. Use the following commands:
git add -A
git commit -m "your comment here"
All your changes will be in the remote repository in GitHub, which can now be merged into the Well-Architected Labs repository.
Additional Validation Step for New Labs
- New labs require an additional validation step of two peer reviews. Please have two peers review your lab step by step to confirm it is working as expected prior to submitting a pull request.
Perform a pull request
All the changes are now in your remote repository, let’s do a pull request to merge it into the public Well-Architected Labs repository:
- Go to the your GitHub Well-Architected Labs remote repository http://github.com/(username)/aws-well-architected-labs/pulls)
- Make sure you update with your username
- Click Pull Request
- Click compare across forks
- Select your fork on the right side as head repository
- Review the changes, and click Create pull request
- Edit the info (this is public – be careful and add a brief description of the edit or addition)
- Make sure to add the label of the Well-Architected Pillar (i.e. COST)
- Click Create pull request
GitHub provides additional document on forking a repository
creating a pull request
Thank you for your contribution. The Well-Architected team will receive a notification of the pull request, we will review and commit the change or reach out with any questions.
Clean up your local and remote repositories, delete them if there is not additional work.
- Go to your remote repository, modify the link: https://github.com/(username)/aws-well-architected-labs
- Click Settings
- Scroll down under Danger Zone and click Delete this repository
- Confirm & click delete
- Clean up your local repository by deleting the directory created previously
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct
For more information see the Code of Conduct FAQ
email@example.com with any additional questions or comments.
Security issue notifications
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page
. Please do not create a public GitHub issue.
See the LICENSE
file for our project’s licensing. We will ask you to confirm the licensing of your contribution.
We may ask you to sign a Contributor License Agreement (CLA)
for larger changes.