LocalStack is a community driven project that aims to help developers emulate AWS services locally, without connecting to any cloud provider! The community version of LocalStack has grown exceptionally and now supports various AWS services, which is detailed on our feature coverage.
This document serves the need for a guide for contributors to help them understand the overall organization of the LocalStack community projects. As an emerging open-source community, we have a plethora of work that we need to do and complete, and it is not just limited to code.
From a contribution perspective, you can work on writing examples, triaging issues and pull requests, submitting bug fixes, suggesting improvements and making our documentation accessible to more users.
Before submitting any contributions to LocalStack, you should complete the following prerequisties. Having completed and understood the basic philosophy around these steps would make it easier for you to land your first contribution.
LocalStack governs its participants according to the Contributor Covenant Code of Conduct. As a contributor, you agree to uphold this code. Please report unacceptable behavior to [email protected].
To contribute code contributions, setting up a development environment is required. Review the LocalStack developer guide to understand how you can setup the environment and make the desirable changes. It is also recommended to look at our open issues for better context around contributions we are looking for.
When you submit changes, your submissions are understood to be under the same Apache 2.0 License that covers the project. Feel free to contact the maintainers if that's a concern.
We assume that you have already set up the project on your local machine by following up on the official documentation. If you are stuck, do reach out to one of the maintainers to help you out in the process.
Our contribution flow is very straightforward and follows an issue-pull request workflow. The contributors need to fork the repository for having their contributions landed on the project. If you are looking to contribute, we have laid down a series of steps that we would like you to follow.
We would recommend you to go through the Issues of the specific project that you would like to contribute to. You can additionally:
- Understand and identify the gaps in the code and documentation.
- Understand the code formatting, stylistic principles and comment format that is being followed.
- Test specific pull requests and the project on your local machine and see if the changes are desirable.
Exploring the issues and pull requests, will give you an idea of how the contribution flow works. Upon finding something to work on, you can either request for the issue to be assigned to you (if someone else has created the Issue) or you can make your own. To ensure that the issue is received positively by the maintainers make sure of the following:
- If you are filing a Bug report, make sure that the report includes all the information that the maintainer needs to reproduce the issue.
- If you are filing a feature request, make sure you pitch in your idea well and it should be constructive.
- Before opening a new issue, make sure a similar one has not already been created or is being worked on by someone else.
To make sure you land a great contribution, we would request you to follow the standard Git & GitHub workflow to know about code collaboration. If you are not already familiar with Git, we would suggest you follow the official Git documentation.
We would recommend:
- Every Pull Request should have the corresponding issue linked to it.
- Every Pull Request should pass the automated CI checks.
- Every Pull Request should be as atomic as possible.
- Every Pull Request should include a test verifying the new/fixed behavior.
Atomic commits correspond to the smallest, most meaningful change you can make to the code. You can keep your pull request as a draft if you are still working on it. Upon completion, you can mark the pull request is ready to review for further comments and feedback.
After landing your pull request, the maintainers will review it and provide actionable feedback. Don't hesitate to contact the maintainers on the Slack community channels if you are awaiting your first review or you have made all the required changes.
Maintainers expect the comments to be resolved once a review has been completed. You can provide updates if you are still working on it, to help us understand the areas where we can help. After the pull request is reviewed and approved, we would squash all the commits before we officially merge it.