Skip to content

Commit f2efc76

Browse files
committed
Updating Documentation
* Shortened README.md and removed comparison chart as we are essentially feature complete with the parent project. * Broke out contributing into its own doc * Added a Code of Conduct document for those who contribute
1 parent 86201cf commit f2efc76

File tree

3 files changed

+286
-144
lines changed

3 files changed

+286
-144
lines changed

CODE_OF_CONDUCT.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment,
6+
the maintainers and contributors of **Git Py Stats** pledge to make
7+
participation in our project and our community a harassment-free experience for
8+
everyone, regardless of age, body size, disability, ethnicity, gender identity
9+
and expression, level of experience, nationality, personal appearance, race,
10+
religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
- Using welcoming and inclusive language.
18+
- Being respectful of differing viewpoints and experiences.
19+
- Gracefully accepting constructive criticism.
20+
- Focusing on what is best for the community.
21+
- Showing empathy towards other community members.
22+
23+
Examples of unacceptable behavior include:
24+
25+
- Harassment, intimidation, or abusive language.
26+
- Trolling or insulting comments.
27+
- Personal or political attacks.
28+
- Publishing others' private information.
29+
- Disruptive behavior in community spaces.
30+
31+
## Enforcement Responsibilities
32+
33+
Community leaders are responsible for clarifying and enforcing our standards of
34+
acceptable behavior and will take appropriate and fair corrective action in
35+
response to any behavior that they deem inappropriate.
36+
37+
## Reporting Guidelines
38+
39+
If you have any concerns about any aspect of the community, please reach out to
40+
the project maintainers via
41+
[GitHub Issues](https://github.com/tomice/git-py-stats/issues).
42+
43+
All reports will remain confidential.
44+
45+
## Attribution
46+
47+
This Code of Conduct is adapted from the
48+
[Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html),
49+
version 2.0, available at [https://www.contributor-covenant.org](https://www.contributor-covenant.org).
50+
51+
---
52+
53+
Thank you for helping to make **Git Py Stats** a welcoming and inclusive community!

CONTRIBUTING.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
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

Comments
 (0)