-
-
Notifications
You must be signed in to change notification settings - Fork 57
/
Copy pathCONTRIBUTING
128 lines (75 loc) · 4.3 KB
/
CONTRIBUTING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
============
Contributing
============
.. _prs: https://github.com/mstuttgart/brazilcep/pulls
.. _`main branch`: https://github.com/mstuttgart/brazilcep/tree/main
Thank you for considering contributing! This document outlines the various ways you can contribute to this project and how to get started.
Bug Reports and Feature Requests
================================
Found a Bug?
------------
Before reporting an issue, please perform `a quick search <https://github.com/mstuttgart/brazilcep/issues>`_ to check if it has already been reported. If it exists, feel free to comment on the existing issue. Otherwise, open `a new GitHub issue <https://github.com/mstuttgart/brazilcep/issues>`_.
When reporting a bug, ensure you include:
* A clear and concise title.
* A detailed description with relevant information.
* Steps to reproduce the issue and the expected behavior.
* If possible, a code sample or an executable test case demonstrating the issue.
Have a Suggestion for an Enhancement or New Feature?
----------------------------------------------------
We use GitHub issues to track feature requests. Before creating a feature request:
* Ensure you have a clear idea of the enhancement. If unsure, consider discussing it first in a GitHub issue.
* Check the documentation to confirm the feature does not already exist.
* Perform `a quick search <https://github.com/mstuttgart/brazilcep/issues>`_ to see if the feature has already been suggested.
When submitting a feature request, please:
* Provide a clear and descriptive title.
* Explain why the enhancement would be useful, possibly referencing similar features in other libraries.
* Include code examples to demonstrate how the feature would be used.
Contributions are always welcome and greatly appreciated!
Contributing Fixes and New Features
===================================
When contributing fixes or new features, start by forking or branching from the `main branch`_ to ensure you work on the latest code and minimize merge conflicts.
All contributed PRs_ must include valid test coverage to be considered for merging. If you need help with writing tests, don't hesitate to ask.
Thank you for your support!
Running Tests
-------------
To set up the development environment and install all required dependencies, run:
.. code-block:: shell
$ virtualenv -p python3 .venv
$ source .venv/bin/activate
$ make setup
The project provides automated style checks, tests, and coverage reports:
.. code-block:: shell
$ make check
You can also run them individually:
.. code-block:: shell
$ make pre-commit
$ make test
To retrieve uncovered lines, use:
.. code-block:: shell
$ make coverage
To run specific tests, use the ``pytest`` command:
.. code-block:: shell
$ pytest tests/test_apicep.py
For more granular testing:
.. code-block:: shell
$ pytest tests/test_apicep.py::test_fetch_address_success
To run tests against the real API, create a `.env` file in the project's root directory with the following content:
.. code-block:: ini
SKIP_REAL_TEST=False
This will enable tests that interact with the live API. Ensure you have the necessary permissions and understand the implications of running tests against the real API.
Code Style
----------
BrazilCEP uses a collection of tools to maintain consistent code style. These tools are orchestrated using `pre-commit`_, which can be installed locally to check your changes before opening a PR. The CI process will also run these checks before merging.
To run pre-commit checks locally:
.. code-block:: shell
$ make pre-commit
The full list of formatting requirements is specified in the `.pre-commit-config.yaml`_ file located in the project's root directory.
.. _pre-commit: https://pre-commit.com/
.. _.pre-commit-config.yaml: https://github.com/mstuttgart/brazilcep/blob/main/.pre-commit-config.yaml
Building Sphinx Documentation
-----------------------------
.. _readthedocs.io: https://brazilcep.readthedocs.io/
The project includes Sphinx documentation sources under ``./docs/source``, which are published online at `readthedocs.io`_.
High-quality documentation is essential for any project. If you're not familiar with reStructuredText for Sphinx, you can read a primer `here`__.
__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
Thank you for your contribution!