Before you start coding, set up your development environment and brush up on the following topics.
Before you start
What you must set up:
- Get a GitHub account.
- We use GitHub for source control. The GitHub organization for AWS Partner Solutions is at https://github.com/aws-quickstart.
- We use SSH authentication in the submodules, so if you want to contribute to the Partner Solutions, you must have your public key registered in your GitHub account.
- For security reasons, you must enable two-factor authentication (2FA) on your account.
- Choose an integrated development environment (IDE) such as VIM, Visual Studio Code, Atom, Sublime Text, or PyCharm.
What you must know:
- Git commands and concepts, as explained at https://git-scm.com/doc, especially in the following sections:
- JSON or YAML.
- JSON and YAML are the two supported formats for AWS CloudFormation templates. AWS CloudFormation doesn’t support all YAML features.
- AWS CloudFormation. Here are some useful links:
- AWS services that you might want to include in your deployment to improve the usefulness of your cloud architecture:
About our GitHub organization
AWS Partner Solutions are typically hosted in the AWS Quick Start GitHub organization at https://github.com/aws-quickstart. After we approve your Partner Solution for publication, we create a private GitHub repository for you within this organization and give you read access to its contents. You must then fork the repository to make your changes.
To commit code into this repository, you must create pull requests. When your development work and testing are complete and the Partner Solution is ready for publication, we make the GitHub repository public.
The GitHub repositories follow these standards:
Repository names typically start with
quickstart-and are followed by the company name and product name with dashes as delimiters. If the Partner Solution architecture includes multiple solutions, we also add the workload or use case name. The repository names and the folders names must be lowercase, and we recommend that file names be lowercase as well. Example:
- The GitHub repository for each Partner Solution includes the following branches:
- main for the code, which is copied to the S3 bucket for publication.
- doc-edits, an orphan branch for documentation in progress. This branch must not contain source code. While it’s common to switch branches by using the command
git checkout <branch name>, do not do this with orphan branches since this process may not clear all elements out of the previous branch. Instead, clone
doc-editsto a separate location on your local system. This approach prevents the branches from getting polluted.
- gh-pages for the live deployment guide, which is generated from pull requests.
- Feature branches, as necessary, for planned updates.
- The GitHub repository for each Partner Solution includes the following folders:
- scripts: Contains the scripts and configuration files that are used in the Partner Solution; for example, to orchestrate the bootstrap, install or configure an app, or update a host.
- submodules: Used for any referenced Partner Solutions that are configured as submodules of the Partner Solution. These follow the naming convention /submodules/quickstart-repo-name where the contents are synced at a specific commit level. For more information, refer to the Submodules section of this guide.
- templates: Contains the AWS CloudFormation templates for the Partner Solution. All templates use the .template file extension.
- The following files are added when we create the repository:
- README.md: A few standard lines that point to documentation related to this Partner Solution. For an example, refer to the readme for XQ Message Zero-Trust Gateway on AWS.
- NOTICE.txt: Copyright notice. Do not modify this file.
- LICENSE.txt: Apache 2.0 license. Do not modify this file.
- CODEOWNERS: Do not modify this file.
- .metadata: Defines the language of the Partner Solution, in this case CloudFormation.
- Do not store licensed software in your repository.