1  # Contributing Guidelines
  2  
  3  Thank you for your interest in contributing to our project. Whether it's a bug
  4  report, new feature, correction, or additional documentation, we greatly value
  5  feedback and contributions from our community.
  6  
  7  Please read through this document before submitting any issues or pull requests
  8  to ensure we have all the necessary information to effectively respond to your
  9  bug report or contribution.
 10  
 11  ## Development
 12  
 13  To setup a development environment, you'll need
 14  [Node.js](https://nodejs.org/en/) and [yarn](https://yarnpkg.com/).
 15  
 16  Fresh full build:
 17  
 18  1. Clone the repo
 19  2. Run `yarn install`
 20  3. Run `yarn build`
 21  
 22  You can also use these more granular scripts:
 23  
 24  - `yarn compile`: compile code to JavaScript
 25  - `yarn watch`: watch in the background and compile
 26  - `yarn test`: run all tests and linters
 27  - `yarn compat`: check that APIs do not introduce breaking changes
 28  - `yarn lint`: run eslint and API compatibility
 29  
 30  ### Docker Build
 31  
 32  If you want to use docker to build, test and package your work use the following:
 33  
 34  ```shell script
 35  docker build -t constructs .
 36  ```
 37  
 38  ### Using a local version of this library in a dependency
 39  
 40  If you're doing changes to this library,
 41  you often want to test them being used in a real dependency
 42  (for example, the [AWS CDK](https://github.com/aws/aws-cdk))
 43  to verify the changes work like expected.
 44  To make that easier,
 45  this repository includes a script in the `scripts`
 46  directory that overwrites the version of `constructs`
 47  in a dependency's `node_modules`
 48  with a symbolic link to the local version of `constructs`:
 49  
 50  ```shell script
 51  cd my/project/that/uses/constructs/library
 52  /path/to/source/of/constructs/scripts/link.sh
 53  ```
 54  
 55  ## Reporting Bugs/Feature Requests
 56  
 57  We welcome you to use the GitHub issue tracker to report bugs or suggest
 58  features.
 59  
 60  When filing an issue, please check existing open, or recently closed, issues to
 61  make sure somebody else hasn't already reported the issue. Please try to include
 62  as much information as you can. Details like these are incredibly useful:
 63  
 64  * A reproducible test case or series of steps
 65  * The version of our code being used
 66  * Any modifications you've made relevant to the bug
 67  * Anything unusual about your environment or deployment
 68  
 69  ## Contributing via Pull Requests
 70  
 71  Contributions via pull requests are much appreciated. Before sending us a pull
 72  request, please ensure that:
 73  
 74  1. You are working against the latest source on the *master* branch.
 75  2. You check existing open, and recently merged, pull requests to make sure
 76     someone else hasn't addressed the problem already.
 77  3. You open an issue to discuss any significant work - we would hate for your
 78     time to be wasted.
 79  
 80  To send us a pull request, please:
 81  
 82  1. Fork the repository.
 83  2. Modify the source; please focus on the specific change you are contributing.
 84     If you also reformat all the code, it will be hard for us to focus on your
 85     change.
 86  3. Ensure local tests pass.
 87  4. Commit to your fork using clear commit messages.
 88  5. Send us a pull request, answering any default questions in the pull request
 89     interface.
 90  6. Pay attention to any automated CI failures reported in the pull request, and
 91     stay involved in the conversation.
 92  
 93  GitHub provides additional document on [forking a
 94  repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull
 95  request](https://help.github.com/articles/creating-a-pull-request/).
 96  
 97  
 98  ## Finding contributions to work on
 99  
100  Looking at the existing issues is a great way to find something to contribute
101  on. As our projects, by default, use the default GitHub issue labels
102  (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any
103  'help wanted' issues is a great place to start.
104  
105  
106  ## Code of Conduct
107  
108  This project has adopted the [Amazon Open Source Code of
109  Conduct](https://aws.github.io/code-of-conduct). For more information see the
110  [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
111  opensource-codeofconduct@amazon.com with any additional questions or comments.
112  
113  ## Security issue notifications
114  
115  If you discover a potential security issue in this project we ask that you
116  notify AWS/Amazon Security via our [vulnerability reporting
117  page](http://aws.amazon.com/security/vulnerability-reporting/). Please do
118  **not** create a public github issue.
119  
120  ## Releasing a New Version
121  
122  To release a new version, run `yarn bump` which will:"
123  
124  - Calculate the next version (minor/patch) based on [conventional
125    commits](https://www.conventionalcommits.org/en/v1.0.0/).
126  - Update the [CHANGELOG](./CHANGELOG.md).
127  - Create a git commit and tag.
128  
129  Then, execute:
130  
131  ```shell
132  git push --follow-tags origin master
133  ```
134  
135  Once the commit is pushed to master, the [release
136  workflow](./.github/workflows/release.yml) will be triggered and the new version
137  will be published to all package managers.
138  
139  ## Licensing
140  
141  See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to
142  confirm the licensing of your contribution.
143  
144  We may ask you to sign a [Contributor License Agreement
145  (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger
146  changes.