docs

mwunderl · mwunderl · commit 8591f8e34707 · 2025-07-29T17:59:37.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure
+- Tutorial generation capabilities
+- Content enhancement utilities
+- Documentation analysis tools
+- Integration with AWS services
+
+### Changed
+- N/A
+
+### Fixed
+- N/A
+
+## [0.1.0] - 2025-07-16
+
+### Added
+- Initial release
+- Basic project structure
+- Documentation templates
+- Example tutorials
+
+[Unreleased]: https://github.com/aws/developer-tutorials/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/aws/developer-tutorials/releases/tag/v0.1.0
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,4 +1,74 @@
-## Code of Conduct
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-opensource-codeofconduct@amazon.com with any additional questions or comments.
+# Developer Tutorials Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at developer-tutorials@amazon.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,59 +1,70 @@
-# Contributing Guidelines
+# Contributing to Developer Tutorials
 
-Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
-documentation, we greatly value feedback and contributions from our community.
+Thank you for your interest in contributing to Developer Tutorials! We greatly value feedback and contributions from our 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.
+## Reporting Issues
 
+If you find a bug or have a suggestion for improving the Developer Tutorials, please open an issue in our GitHub repository. When filing an issue, please include:
 
-## Reporting Bugs/Feature Requests
+- A clear description of the issue or suggestion
+- Steps to reproduce the issue
+- Expected behavior
+- Actual behavior
+- Any relevant logs or error messages
+- Your environment (OS, Python version, etc.)
 
-We welcome you to use the GitHub issue tracker to report bugs or suggest features.
+## Contributing Code
 
-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:
+We welcome code contributions through pull requests. Here's how to get started:
 
-* 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
+1. Fork the repository
+2. Create a new branch for your feature or bug fix
+3. Make your changes
+4. Add or update tests as necessary
+5. Run the test suite to ensure all tests pass
+6. Commit your changes with clear, descriptive commit messages
+7. Push your branch to your fork
+8. Open a pull request against the main repository
 
+## Development Setup
 
-## Contributing via Pull Requests
-Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
+To set up your development environment:
 
-1. You are working against the latest source on the *main* branch.
-2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
-3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
+```bash
+# Clone the repository
+git clone https://github.com/aws-samples/sample-developer-tutorials.git
 
-To send us a pull request, please:
+# Navigate to the project directory
+cd sample-developer-tutorials
+```
 
-1. Fork the repository.
-2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
-3. Ensure local tests pass.
-4. Commit to your fork using clear commit messages.
-5. Send us a pull request, answering any default questions in the pull request interface.
-6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+## Generating tutorials
 
-GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
-[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+Follow the instructions in [instra/README.md](instra/README.md)
 
+## Testing
 
-## Finding contributions to work on
-Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
+All new scripts and tutorials need to be tested by the author. Attach a log from a successful test run to the pull request.
 
+## Cleanup
 
-## Code of Conduct
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-opensource-codeofconduct@amazon.com with any additional questions or comments.
+The tool generates a lot of artifacts including intermediate script revisions that generate errors. Submit a pull request with only the final revision of the script and tutorial. Rename these after the use case follow this convention.
+
+```
+├── 001-lightsail-gs
+│   ├── README.md
+│   ├── lightsail-gs.md
+│   └── lightsail-gs.sh
+```
 
+## Documentation
 
-## 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](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
+Add a readme for your contribution that describes its use case.
+
+## Code of Conduct
 
+This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
 
-## Licensing
+## License
 
-See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+By contributing to Developer Tutorials, you agree that your contributions will be licensed under the project's [Apache License 2.0](LICENSE).
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -173,3 +172,19 @@
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -1,17 +1,102 @@
-## My Project
+# AWS Developer Tutorials
 
-TODO: Fill this README out!
+A collection of AWS CLI scripts and tutorials for common AWS service use cases, designed to help developers quickly get started with AWS services through the command line.
 
-Be sure to:
+## Overview
 
-* Change the title in this README
-* Edit your repository description on GitHub
+This repository contains AWS CLI scripts and tutorials that demonstrate how to use AWS services through the command line interface. The scripts are designed to be interactive, handle errors, and clean up resources after use. The tutorials provide step-by-step guidance on how to use the scripts and understand the underlying AWS services.
 
-## Security
+These resources serve three main purposes:
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+1. **Running scripts**: Execute ready-made scripts to quickly set up and explore AWS services
+2. **Reading tutorials**: Learn how AWS services work through detailed tutorials
+3. **Generating new scripts**: Use Amazon Q Developer CLI to create new scripts for additional use cases
 
-## License
+## Repository structure
+
+- `/tuts`: Contains all tutorials and scripts, organized by use case
+- `/instra`: Contains instructions for generating new tutorials and scripts
+
+Each tutorial folder follows a naming convention of `XXX-service-usecase` where XXX is a three-digit number, and contains:
+
+- A shell script (`.sh`) that implements the use case
+- A tutorial (`.md`) that explains the use case and how to use the script
+- Supporting files for documentation and reference
+
+## Running scripts
+
+To run an existing script:
+
+1. Clone this repository or download the specific script you need
+2. Make the script executable: `chmod +x script-name.sh`
+3. Run the script: `./script-name.sh`
+
+The scripts are interactive and will:
+- Prompt for necessary inputs
+- Create AWS resources
+- Show the results of operations
+- Track created resources
+- Offer to clean up resources when done
+
+## Reading tutorials
+
+Each script comes with a detailed tutorial that explains:
+- The AWS service and use case
+- Prerequisites and setup
+- Step-by-step walkthrough of the script's operations
+- Explanation of key AWS CLI commands and parameters
+- Best practices and considerations
+
+To read a tutorial, open the corresponding markdown file in the same folder as the script.
+
+## Generating new scripts
+
+You can use Amazon Q Developer CLI to generate new scripts based on:
+
+1. **Existing scripts**: Use an existing script as a template
+2. **Documentation topics**: Generate a script from AWS documentation
 
-This project is licensed under the Apache-2.0 License.
+### Using existing scripts as templates
+
+```bash
+# Example: Generate a script for IPAM setup using an existing script
+q "Generate a script to set up IPAM for my VPC. Use the following script as an example: 009-vpc-ipam-gs.sh"
+```
+
+### Generating from documentation
+
+```bash
+# Example: Generate a script from AWS Payment Cryptography documentation
+q "read the instructions in the ../../instra/tutorial-gen folder and follow them in order, using this topic: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/getting-started.html when instructed to run the script in step 2b, it's ok to actually run the script and create resources. this is part of the process. when you generate the script, be careful to check required options and option names for each command."
+```
+
+## Prerequisites
+
+- AWS CLI installed and configured with appropriate credentials
+- Bash shell environment
+- Appropriate AWS permissions for the services used in each script
+
+## Contributing
+
+We welcome contributions to expand the collection of tutorials and scripts. To contribute:
+
+1. **Create a new folder** in the `/tuts` directory following the naming convention: `XXX-service-usecase`
+2. **Follow the tutorial generation instructions** in the `/instra/tutorial-gen` folder
+3. **Submit only the final tutorial and script files** after testing and validation
+
+### Folder structure for new contributions
+
+```
+/tuts/XXX-service-usecase/
+├── XXX-service-usecase-script.sh    # The executable script
+├── XXX-service-usecase-tutorial.md      # The tutorial documentation
+└── XXX-service-usecase-README.md          # Brief description of the use case
+```
+
+## Cleanup
+
+All scripts include resource tracking and cleanup functionality. After provisioning and interacting with resources, the scripts provide a list of resources and ask if you want to clean them up. If a script encounters an issue, it attempts to clean up resources that it created before the error.
+
+## License
 
+This project is licensed under the MIT-0 License. See the LICENSE file for details.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,39 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a potential security issue in this project, we ask that you notify AWS Security via our [vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue.
+
+## Supported Versions
+
+Only the latest version of Developer Tutorials is currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| latest  | :white_check_mark: |
+| < latest | :x:                |
+
+## Security Measures
+
+This project implements the following security measures:
+
+- Regular dependency updates
+- Code scanning for vulnerabilities
+- Security review process for all contributions
+- Adherence to AWS security best practices
+
+## Security Recommendations
+
+When using this tool:
+
+1. Keep the tool and its dependencies up to date
+2. Use the latest stable release
+3. Follow the principle of least privilege when configuring AWS credentials
+4. Review the documentation for security-related best practices
+5. Report any security concerns immediately
+
+## Additional Resources
+
+- [AWS Security Documentation](https://docs.aws.amazon.com/security/)
+- [AWS Security Blog](https://aws.amazon.com/blogs/security/)
+- [AWS Security Bulletins](https://aws.amazon.com/security/security-bulletins/)
diff --git a/SUPPORT.md b/SUPPORT.md
