|
| 1 | +# Contributing to the Python Agent |
| 2 | + |
| 3 | +Thanks for your interest in contributing to the |
| 4 | +`New Relic Python Agent`! We look forward to engaging with you. |
| 5 | + |
| 6 | +## How to Contribute |
| 7 | + |
| 8 | +Contributions are always welcome. Before contributing please read the |
| 9 | +[code of |
| 10 | +conduct](https://github.com/newrelic/.github/blob/main/CODE_OF_CONDUCT.md) |
| 11 | +and [search the issue tracker](https://github.com/newrelic/newrelic-python-agent/issues); your issue may have |
| 12 | +already been discussed or fixed in [main]{.title-ref}. To contribute, |
| 13 | +[fork](https://help.github.com/articles/fork-a-repo/) this repository, |
| 14 | +commit your changes, and [send a Pull |
| 15 | +Request](https://help.github.com/articles/using-pull-requests/). |
| 16 | + |
| 17 | +Note that our [code of |
| 18 | +conduct](https://github.com/newrelic/.github/blob/main/CODE_OF_CONDUCT.md) |
| 19 | +applies to all platforms and venues related to this project; please |
| 20 | +follow it in all your interactions with the project and its |
| 21 | +participants. |
| 22 | + |
| 23 | +## How to Get Help or Ask Questions |
| 24 | + |
| 25 | +Do you have questions or are you experiencing unexpected behaviors after |
| 26 | +modifying this Open Source Software? Please engage with the "Build on |
| 27 | +New Relic" space in the [Explorers |
| 28 | +Hub](https://discuss.newrelic.com/c/build-on-new-relic/Open-Source-Agents-SDKs), |
| 29 | +New Relic\'s Forum. Posts are publicly viewable by anyone, please do not |
| 30 | +include PII or sensitive information in your forum post. |
| 31 | + |
| 32 | +## Contributor License Agreement ("CLA") |
| 33 | + |
| 34 | +We\'d love to get your contributions to improve the Python Agent! Keep |
| 35 | +in mind that when you submit your Pull Request, you\'ll need to sign the |
| 36 | +CLA via the click-through using CLA-Assistant. You only have to sign the |
| 37 | +CLA one time per project. If you\'d like to execute our corporate CLA, |
| 38 | +or if you have any questions, please drop us an email at |
| 39 | + |
| 40 | + |
| 41 | +For more information about CLAs, please check out Alex Russell\'s |
| 42 | +excellent post, [Why Do I Need to Sign |
| 43 | +This?](https://infrequently.org/2008/06/why-do-i-need-to-sign-this/). |
| 44 | + |
| 45 | +## Feature Requests |
| 46 | + |
| 47 | +Feature requests should be submitted in the [Issue |
| 48 | +tracker](https://github.com/newrelic/newrelic-python-agent/issues), with a description of the expected behavior & |
| 49 | +use case, where they\'ll remain closed until sufficient interest, [e.g. |
| 50 | +:+1: |
| 51 | +reactions](https://help.github.com/articles/about-discussions-in-issues-and-pull-requests/), |
| 52 | +has been [shown by the |
| 53 | +community](https://github.com/newrelic/newrelic-python-agent/issues?q=label%3A%22votes+needed%22+sort%3Areactions-%2B1-desc). |
| 54 | +Before submitting an Issue, please search for similar ones in the |
| 55 | +[closed |
| 56 | +issues](https://github.com/newrelic/newrelic-python-agent/issues?q=is%3Aissue+is%3Aclosed+label%3Aenhancement). |
| 57 | + |
| 58 | +## Filing Issues & Bug Reports |
| 59 | + |
| 60 | +We use GitHub issues to track public issues and bugs. If possible, |
| 61 | +please provide a link to an example app or gist that reproduces the |
| 62 | +issue. When filing an issue, please ensure your description is clear and |
| 63 | +includes the following information. |
| 64 | + |
| 65 | +- Project version (ex: 1.4.0) |
| 66 | +- Custom configurations (ex: flag=true) |
| 67 | +- Any modifications made to the Python Agent |
| 68 | + |
| 69 | +### A note about vulnerabilities |
| 70 | + |
| 71 | +New Relic is committed to the security of our customers and their data. |
| 72 | +We believe that providing coordinated disclosure by security researchers |
| 73 | +and engaging with the security community are important means to achieve |
| 74 | +our security goals. |
| 75 | + |
| 76 | +If you believe you have found a security vulnerability in this project |
| 77 | +or any of New Relic\'s products or websites, we welcome and greatly |
| 78 | +appreciate you reporting it to New Relic through |
| 79 | +[our bug bounty program](https://docs.newrelic.com/docs/security/security-privacy/information-security/report-security-vulnerabilities/). |
| 80 | + |
| 81 | +## Setting Up Your Environment |
| 82 | + |
| 83 | +This Open Source Software can be used in a large number of environments, |
| 84 | +all of which have their own quirks and best practices. As such, while we |
| 85 | +are happy to provide documentation and assistance for unmodified Open |
| 86 | +Source Software, we cannot provide support for your specific |
| 87 | +environment. |
| 88 | + |
| 89 | +## Developing Inside a Container |
| 90 | + |
| 91 | +To avoid the issues involved with setting up a local environment, |
| 92 | +consider using our prebuilt development container to easily create an |
| 93 | +environment on demand with a wide selection of Python versions |
| 94 | +installed. This also comes with the |
| 95 | +[tox](https://github.com/tox-dev/tox) tool (See Testing Guidelines) and |
| 96 | +a few packages preinstalled. |
| 97 | + |
| 98 | +While we cannot provide direct support in setting up your environment to |
| 99 | +work with this container, we develop it in the open and provide this |
| 100 | +documentation to help reduce the setup burden on new contributors. |
| 101 | + |
| 102 | +### Prerequisites |
| 103 | + |
| 104 | +1. Install [Docker](https://www.docker.com/) for you local operating |
| 105 | + system. |
| 106 | + |
| 107 | +2. Login to the [GitHub Container |
| 108 | + Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) |
| 109 | + through Docker. |
| 110 | + |
| 111 | +3. |
| 112 | + |
| 113 | + Install Either: |
| 114 | + |
| 115 | + : - [VS Code](https://code.visualstudio.com/) onto your local |
| 116 | + system (recommended). |
| 117 | + - The [Dev Container |
| 118 | + CLI](https://github.com/devcontainers/cli) in your terminal. |
| 119 | + (Requires a local copy of |
| 120 | + [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).) |
| 121 | + |
| 122 | +### Steps for VS Code |
| 123 | + |
| 124 | +1. Ensure Docker is running. |
| 125 | +2. Install the [VS Code Extension for Dev |
| 126 | + Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
| 127 | + into VS Code. |
| 128 | +3. In VS Code, open the command pallette (Ctrl-Shift-P on Windows/Linux |
| 129 | + or Cmd-Shift-P on Mac) and search for and run \"Dev Containers: |
| 130 | + Rebuild and Reopen in Container\". |
| 131 | +4. Wait for the container to build and start. This may take a long time |
| 132 | + to pull the first time the container is run, subsequent runs should |
| 133 | + be faster thanks to caching. |
| 134 | +5. To update your container, open the command pallette and run \"Dev |
| 135 | + Containers: Rebuild Without Cache and Reopen in Container\". |
| 136 | + |
| 137 | +### Steps for Command Line Editor Users (vim, etc.) |
| 138 | + |
| 139 | +1. Ensure Docker is running. |
| 140 | +2. From the root of this repository, run |
| 141 | + `devcontainer up --workspace-folder=.` to start the container. The |
| 142 | + running container ID will be displayed, which is useful for |
| 143 | + subsequent steps. |
| 144 | +3. To gain shell access to the container, run |
| 145 | + `docker exec -it <container-id> /bin/bash`. Alternative shells |
| 146 | + include `zsh` and `fish`. |
| 147 | +4. Navigate to the `/workspaces` folder to find your source code. |
| 148 | +5. To stop the container, run `exit` on any open shells and then run |
| 149 | + `docker stop <container-id>`. `docker ps` may be helpful for finding |
| 150 | + the ID if you\'ve lost it. |
| 151 | + |
| 152 | +### Personalizing Your Container |
| 153 | + |
| 154 | +1. If you use a dotfiles repository (such as |
| 155 | + [chezmoi](https://www.chezmoi.io/)), you can configure your |
| 156 | + container to clone and install your dotfiles using [VS Code dotfile |
| 157 | + settings](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories). |
| 158 | +2. To install extra packages and features, you can edit your local copy |
| 159 | + of the .devcontainer/devcontainer.json file to use specific [Dev |
| 160 | + Container Features](https://containers.dev/features). A few common |
| 161 | + needs are already included but commented out. |
| 162 | + |
| 163 | +## Pull Request Guidelines |
| 164 | + |
| 165 | +Before we can accept a pull request, you must sign our [Contributor |
| 166 | +Licensing Agreement](#contributor-license-agreement-cla), if you have |
| 167 | +not already done so. This grants us the right to use your code under the |
| 168 | +same Apache 2.0 license as we use for this project in general. |
| 169 | + |
| 170 | +Minimally, the [test suite](#testing-guidelines) must pass for us to |
| 171 | +accept a PR. Ideally, we would love it if you also added appropriate |
| 172 | +tests if you\'re implementing a feature! |
| 173 | + |
| 174 | +Please note that integration tests will be run internally before |
| 175 | +contributions are accepted. |
| 176 | + |
| 177 | +Additionally: |
| 178 | + |
| 179 | +1. Ensure any install or build dependencies are removed before the end |
| 180 | + of the layer when doing a build. |
| 181 | +2. Increase the version numbers in any examples files and the README.md |
| 182 | + to the new version that this Pull Request would represent. The |
| 183 | + versioning scheme we use is [SemVer](http://semver.org/). |
| 184 | +3. You may merge the Pull Request in once you have the sign-off of two |
| 185 | + other developers, or if you do not have permission to do that, you |
| 186 | + may request the second reviewer to merge it for you. |
| 187 | + |
| 188 | +## Testing Guidelines |
| 189 | + |
| 190 | +The Python Agent uses [tox](https://github.com/tox-dev/tox) for testing. |
| 191 | +The repository uses tests in tests/. |
| 192 | + |
| 193 | +You can run these tests by entering the tests/ directory and then |
| 194 | +entering the directory of the tests you want to run. Then, run the |
| 195 | +following command: |
| 196 | + |
| 197 | +`tox -c tox.ini -e [test environment]` |
0 commit comments