|
| 1 | +# Contributing to Git Py Stats |
| 2 | + |
| 3 | +Thank you for your interest in contributing to **Git Py Stats**! |
| 4 | +We welcome contributions of all kinds, including bug reports, feature requests, |
| 5 | +documentation improvements, and code enhancements. |
| 6 | + |
| 7 | +## Table of Contents |
| 8 | + |
| 9 | +- [Code of Conduct](#code-of-conduct) |
| 10 | +- [How to Contribute](#how-to-contribute) |
| 11 | + - [Reporting Issues](#reporting-issues) |
| 12 | + - [Suggesting Features](#suggesting-features) |
| 13 | + - [Submitting Pull Requests](#submitting-pull-requests) |
| 14 | +- [Coding Standards](#coding-standards) |
| 15 | +- [Testing](#testing) |
| 16 | + - [Running Tests](#running-tests) |
| 17 | + - [Additional Tips](#additional-tips) |
| 18 | +- [Style Guidelines](#style-guidelines) |
| 19 | +- [Acknowledgments](#acknowledgments) |
| 20 | + |
| 21 | +## Code of Conduct |
| 22 | + |
| 23 | +Please read our [Code of Conduct](CODE_OF_CONDUCT.md) to understand the |
| 24 | +expectations for participation in this project. |
| 25 | + |
| 26 | +## How to Contribute |
| 27 | + |
| 28 | +### Reporting Issues |
| 29 | + |
| 30 | +If you encounter any bugs or have suggestions for improvements, |
| 31 | +please [open an issue](https://github.com/tomice/git-py-stats/issues). |
| 32 | +When reporting an issue, please include the following: |
| 33 | + |
| 34 | +- A clear and descriptive title. |
| 35 | +- A detailed description of the problem or suggestion. |
| 36 | +- Steps to reproduce the issue (if applicable). |
| 37 | +- Any relevant screenshots or error messages. |
| 38 | + |
| 39 | +### Suggesting Features |
| 40 | + |
| 41 | +Have an idea for a new feature? We'd love to hear it! Please create an issue |
| 42 | +with the tag `feature request` and provide as much detail as possible about |
| 43 | +the proposed functionality. |
| 44 | + |
| 45 | +### Submitting Pull Requests |
| 46 | + |
| 47 | +Contributions are made via pull requests. Here's how to submit one: |
| 48 | + |
| 49 | +1. **Fork the Repository** |
| 50 | + |
| 51 | + Click the "Fork" button at the top right of this repository page to |
| 52 | + create your own fork. |
| 53 | + |
| 54 | +2. **Clone Your Fork** |
| 55 | + |
| 56 | + ```bash |
| 57 | + git clone https://github.com/your-username/git-py-stats.git |
| 58 | + cd git-py-stats |
| 59 | + ``` |
| 60 | + |
| 61 | +3. **Create a New Branch** |
| 62 | + |
| 63 | + It's best to create a new branch for each significant change. |
| 64 | + |
| 65 | + ```bash |
| 66 | + git checkout -b feature/your-feature-name |
| 67 | + ``` |
| 68 | + |
| 69 | +4. **Make Your Changes** |
| 70 | + |
| 71 | + - Try to follow the [PEP 8](https://pep8.org/) style guide. |
| 72 | + - Add or update tests as necessary. |
| 73 | + - Update documentation if your changes require it. |
| 74 | + |
| 75 | +5. **Commit Your Changes** |
| 76 | + |
| 77 | + Write clear and descriptive commit messages. |
| 78 | + |
| 79 | + ```bash |
| 80 | + git commit -m "Add feature: description of your feature" |
| 81 | + ``` |
| 82 | + |
| 83 | +6. **Push to Your Fork** |
| 84 | + |
| 85 | + ```bash |
| 86 | + git push origin feature/your-feature-name |
| 87 | + ``` |
| 88 | + |
| 89 | +7. **Open a Pull Request** |
| 90 | + |
| 91 | + Navigate to the original repository and click on "New Pull Request". |
| 92 | + Provide a clear description of your changes and reference any related issues |
| 93 | + should they exist. |
| 94 | + |
| 95 | +## Coding Standards |
| 96 | + |
| 97 | +- **Language**: |
| 98 | + We currently have a minimum requirement of Python 3.8. While this code may |
| 99 | + work on Python 3 versions below that, it is not guaranteed. |
| 100 | +- **Dependencies**: |
| 101 | + Git Py Stats should not have any dependencies outside of Python 3 and `git`. |
| 102 | + That means nobody should ever have to type in `pip foo` before being able to |
| 103 | + run this program. |
| 104 | +- **Style Guide**: |
| 105 | + We use [Black](https://pypi.org/project/black/) for auto formatting code in |
| 106 | + the repo before it gets merged for style consistency. |
| 107 | +- **Naming Conventions**: |
| 108 | + Use clear and descriptive names for variables, functions, and classes. |
| 109 | + When in doubt, always try to follow [PEP 8](https://pep8.org/). |
| 110 | +- **Documentation**: |
| 111 | + Include docstrings for all public modules, functions, classes, and methods. |
| 112 | + Also include type hints for functions, classes, and methods. |
| 113 | + |
| 114 | +While not strict, try to keep documentation around 80 columns per line. |
| 115 | + |
| 116 | +## Testing |
| 117 | + |
| 118 | +This project uses Python's built-in |
| 119 | +[unittest](https://docs.python.org/3/library/unittest.html) testing framework. |
| 120 | +Ensure that all tests pass before submitting a pull request. |
| 121 | + |
| 122 | +### Running Tests |
| 123 | + |
| 124 | +1. **Navigate to the Project Directory**: |
| 125 | + |
| 126 | + ```bash |
| 127 | + cd git-py-stats |
| 128 | + ``` |
| 129 | + |
| 130 | +2. **Run All Tests**: |
| 131 | + |
| 132 | + You can run all tests using the `unittest` discovery mode, which will |
| 133 | + automatically find and execute all test files named `test_*.py` |
| 134 | + within the `git_py_stats/tests/` directory: |
| 135 | + |
| 136 | + ```bash |
| 137 | + python3 -m unittest discover -s git_py_stats/tests |
| 138 | + ``` |
| 139 | + |
| 140 | +3. **Run a Specific Test File**: |
| 141 | + |
| 142 | + To run a specific test file, you can use: |
| 143 | + |
| 144 | + ```bash |
| 145 | + python3 -m unittest git_py_stats.tests.test_generate_cmds |
| 146 | + ``` |
| 147 | + |
| 148 | +### Additional Tips |
| 149 | + |
| 150 | +- Ensure that all test files follow the naming convention `test_*.py`. |
| 151 | +- To view more detailed output, use the `-v` (verbose) flag: |
| 152 | + |
| 153 | + ```bash |
| 154 | + python3 -m unittest discover -s git_py_stats/tests -v |
| 155 | + ``` |
| 156 | + |
| 157 | +- To run all tests automatically and display a summary of results: |
| 158 | + |
| 159 | + ```bash |
| 160 | + python3 -m unittest discover -s git_py_stats/tests |
| 161 | + ``` |
| 162 | + |
| 163 | +- If you need help writing tests, here are tutorials and books that might help: |
| 164 | + - [Python's unittest docs](https://docs.python.org/3/library/unittest.html) |
| 165 | + - [Python's unittest.mock docs](https://docs.python.org/3/library/unittest.mock.html) |
| 166 | + - [Obey the Testing Goat](https://www.obeythetestinggoat.com/pages/book.html#toc) |
| 167 | + |
| 168 | +## Style Guidelines |
| 169 | + |
| 170 | +- Write clear and concise code. |
| 171 | +- Avoid unnecessary complexity. |
| 172 | +- Ensure that your code is readable and maintainable. |
| 173 | +- Comment your code where necessary to explain complex logic. |
| 174 | + |
| 175 | +## Acknowledgments |
| 176 | + |
| 177 | +- Thanks to each and every one of the contributors of |
| 178 | + [git-quick-stats](https://github.com/arzzen/git-quick-stats) for inspiring |
| 179 | + this project. Without them, this project would not exist. |
| 180 | +- Special thanks to all the contributors who help make Git Py Stats better! |
0 commit comments