• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Contributing to gRPC Python
2We're thrilled you're interested in contributing to gRPC Python!  Our vibrant community is the heart of this project. Your expertise and ideas are invaluable, so join us in shaping the future of gRPC Python.
3
4## Legal Requirements
5**Sign the CLA:** Before your PR can be reviewed, you'll need to sign the [CNCF Contributor License Agreement (CLA)](https://identity.linuxfoundation.org/projects/cncf).
6
7## Community Code of Conduct
8gRPC Python follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
9
10
11## Guidelines
12gRPC Python Follows [gRPC Guidelines for Pull Requests](https://github.com/grpc/grpc/blob/master/CONTRIBUTING.md#guidelines-for-pull-requests)
13
14## There are many ways to contribute!
15
16* **Code:** Fix bugs, add new features, or improve existing code.
17* **Documentation:** Improve tutorials, guides, or API reference documentation.
18* **Community:** Answer questions on forums, help triage issues, or write blog posts.
19* **Testing:** Help ensure the quality of gRPC Python by writing tests or reporting bugs.
20
21
22## Writing Your First Patch for gRPC Python
23
24Ready to dive in?  We'll walk you through the entire process of making your first contribution, from identifying an issue to submitting your changes for review. Don't worry if you're new to open source – our documentation and helpful community will ensure a smooth experience.
25
26### Prerequisites
27
28* **Git:** You should have Git installed on your system. If not, download and install it from the [official Git website](https://git-scm.com/).
29* **GitHub Account:** You'll need a GitHub account to fork the repository and submit pull requests.
30* **Python:** You should have a good understanding of Python programming. If you're new to Python, there are many resources available online to get you started. You can find the official documentation on the [Python website](https://www.python.org/doc/).
31* **gRPC Concepts:** Familiarize yourself with the basics of gRPC, including concepts like protocol buffers, services, clients, and servers. Refer to the [gRPC documentation](https://grpc.io/docs/) for an overview.
32* **Bazel:** Bazel is one of the build systems used for gRPC. To install it, follow the instructions for your operating system on the [Bazel website](https://bazel.build/install).
33
34### Steps to Contributing to gRPC Python
35
361. **Find an Issue:**
37   * **Browse Open Issues:** Look for issues labeled "[help wanted](https://github.com/grpc/grpc/issues?q=is%3Aopen+label%3A%22disposition%2Fhelp+wanted%22)" on the [gRPC Python issue tracker](https://github.com/grpc/grpc/issues?q=is%3Aissue+is%3Aopen+label%3Alang%2Fpython+sort%3Aupdated-desc).
38   * **Ask for Help:** If you're unsure where to start or need clarification on an issue, feel free to ask questions on the [gRPC forum](https://groups.google.com/g/grpc-io).
392. **Get a Copy of the gRPC Python Development Version:**
40   * **Fork:**  Click the "Fork" button on the top right of the [gRPC repository page](https://github.com/grpc/grpc) to create a copy of the repository under your GitHub account.
41   * **Clone your fork:**
42   ```git clone https://github.com/<your-username>/grpc.git```
43   * **Initialize and Update Submodules:**
44   ```bash
45   cd grpc
46   git submodule update --init --recursive
47   ```
48   * **Create a Branch:** Make your changes on a new branch:
49   ```git checkout -b my-feature-branch```
503. **Setting up Your Local System for Development and Testing:**
51   * Create a new virtual environment by running:```python -m venv ~/.virtualenvs/grpc-python```
52   * Activate the environment: ```source ~/.virtualenvs/grpc-python/bin/activate```
53   * Install Dependencies: ```pip install -r requirements.txt```
544. **Run Tests:**
55   * Before making any changes, run the existing test suite to ensure your environment is set up correctly:
56   * **Using Bazel (Recommended):**
57     * To run a single unit test:
58       ```bash
59       bazel test --cache_test_results=no "//src/python/grpcio_tests/tests/unit:_abort_test"
60       ```
61     * To execute all unit tests for Python:
62       ```bash
63       bazel test --cache_test_results=no "//src/python/..."
64       ```
65   * **Using Provided Scripts (Alternative):**
66     * Install Python Modules:
67       ```bash
68       ./tools/distrib/install_all_python_modules.sh
69       ```
70     * Run Tooling Tests:
71       ```bash
72       ./tools/distrib/run_python_tooling_tests.sh
73       ```
74   * **Verify No Failures:** Make sure all tests pass before submitting your patch.
755. **Commit & Push Changes:**
76    * **Commit:** `git commit -m "Add new feature: brief description"`  (Make sure your commit message is clear and concise.)
77    * **Push:** `git push origin my-feature-branch`
786. **Open a Pull Request (PR):**
79    * **Go to GitHub:** Visit the original gRPC Python repository on GitHub.
80    * **Click "New Pull Request":** Compare your branch with the main branch and submit your pull request.
81    * **Provide a Description:**  Write a clear explanation of your changes, referencing the relevant issue(s).
827. **Code Review:**
83    * **Wait for Feedback:** Maintainers will review your PR and provide feedback.
84    * **Respond to Comments:**  Address any questions or concerns raised during the review.
85    * **Make Revisions:** Update your code as needed based on the feedback.
86
87## Code Style
88
89* **Pythonic Code:** Follow the [PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/) for Python code.
90* **Type Hints:** Use type hints to improve code readability and maintainability.
91* **Formatting:** Use [Black](https://black.readthedocs.io/en/stable/) for automatic code formatting.
92
93