Skip to content

Commit 23217c5

Browse files
zariiii9003zariiii9003
committed
update contribution guidelines
1 parent 4f129e5 commit 23217c5

File tree

3 files changed

+196
-88
lines changed

3 files changed

+196
-88
lines changed

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Please read the [Development - Contributing](https://python-can.readthedocs.io/en/stable/development.html#contributing) guidelines in the documentation site.
1+
Please read the [Development - Contributing](https://python-can.readthedocs.io/en/main/development.html#contributing) guidelines in the documentation site.

‎doc/development.rst‎

Lines changed: 188 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,234 @@
11
Developer's Overview
22
====================
33

4+
Quick Start for Contributors
5+
----------------------------
6+
* Fork the repository on GitHub and clone your fork.
7+
* Create a new branch for your changes.
8+
* Set up your development environment.
9+
* Make your changes, add/update tests and documentation as needed.
10+
* Run `tox` to check your changes.
11+
* Push your branch and open a pull request.
412

513
Contributing
614
------------
715

8-
Contribute to source code, documentation, examples and report issues:
9-
https://github.com/hardbyte/python-can
16+
Welcome! Thank you for your interest in python-can. Whether you want to fix a bug,
17+
add a feature, improve documentation, write examples, help solve issues,
18+
or simply report a problem, your contribution is valued.
19+
Contributions are made via the `python-can GitHub repository <https://github.com/hardbyte/python-can>`_.
20+
If you have questions, feel free to open an issue or start a discussion on GitHub.
1021

11-
Note that the latest released version on PyPi may be significantly behind the
12-
``main`` branch. Please open any feature requests against the ``main`` branch
22+
If you're new to the codebase, see the next section for an overview of the code structure.
23+
For more about the internals, see :ref:`internalapi` and information on extending the ``can.io`` module.
1324

14-
There is also a `python-can <https://groups.google.com/forum/#!forum/python-can>`__
15-
mailing list for development discussion.
25+
Code Structure
26+
^^^^^^^^^^^^^^
1627

17-
Some more information about the internals of this library can be found
18-
in the chapter :ref:`internalapi`.
19-
There is also additional information on extending the ``can.io`` module.
28+
The modules in ``python-can`` are:
2029

30+
+---------------------------------+------------------------------------------------------+
31+
|Module | Description |
32+
+=================================+======================================================+
33+
|:doc:`interfaces <interfaces>` | Contains interface dependent code. |
34+
+---------------------------------+------------------------------------------------------+
35+
|:doc:`bus <bus>` | Contains the interface independent Bus object. |
36+
+---------------------------------+------------------------------------------------------+
37+
|:doc:`message <message>` | Contains the interface independent Message object. |
38+
+---------------------------------+------------------------------------------------------+
39+
|:doc:`io <file_io>` | Contains a range of file readers and writers. |
40+
+---------------------------------+------------------------------------------------------+
41+
|:doc:`broadcastmanager <bcm>` | Contains interface independent broadcast manager |
42+
| | code. |
43+
+---------------------------------+------------------------------------------------------+
2144

22-
Pre-releases
23-
------------
45+
Step-by-Step Contribution Guide
46+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2447

25-
The latest pre-release can be installed with::
48+
1. **Fork and Clone the Repository**
2649

27-
pip install --upgrade --pre python-can
50+
* Fork the python-can repository on GitHub to your own account.
51+
* Clone your fork:
2852

53+
.. code-block:: shell
2954
55+
git clone https://github.com/<your-username>/python-can.git
56+
cd python-can
3057
31-
Building & Installing
32-
---------------------
58+
* Create a new branch for your work:
3359

34-
The following assumes that the commands are executed from the root of the repository:
60+
.. code-block:: shell
3561
36-
The project can be built with::
62+
git checkout -b my-feature-branch
3763
38-
pipx run build
39-
pipx run twine check dist/*
64+
* Ensure your branch is up to date with the latest changes from the main repository.
65+
First, add the main repository as a remote (commonly named `upstream`) if you haven't already:
4066

41-
The project can be installed in editable mode with::
67+
.. code-block:: shell
4268
43-
pip install -e .
69+
git remote add upstream https://github.com/hardbyte/python-can.git
4470
45-
The unit tests can be run with::
71+
Then, regularly fetch and rebase from the main branch:
4672

47-
pipx run tox -e py
73+
.. code-block:: shell
4874
49-
The documentation can be built with::
75+
git fetch upstream
76+
git rebase upstream/main
5077
51-
pipx run tox -e docs
78+
2. **Set Up Your Development Environment**
5279

53-
The linters can be run with::
80+
You can use either `pipx <https://pipx.pypa.io/>`__ or `uv <https://docs.astral.sh/uv/>`__
81+
to install development tools. Both methods are supported:
5482

55-
pip install --group lint -e .
56-
black --check can
57-
mypy can
58-
ruff check can
59-
pylint can/**.py can/io doc/conf.py examples/**.py can/interfaces/socketcan
83+
* **pipx** is a tool for installing and running Python applications (such as tox)
84+
in isolated environments, separate from your global Python installation.
85+
It is useful for globally installing CLI tools without affecting your project's dependencies or environment.
86+
* **uv** is a modern Python packaging tool that can quickly create virtual environments and manage dependencies,
87+
including downloading required Python versions automatically.
88+
The `uvx` command also provides functionality similar to pipx,
89+
allowing you to run CLI tools in isolated environments.
6090

91+
Choose the method that best fits your workflow and system setup.
6192

62-
Creating a new interface/backend
63-
--------------------------------
93+
**Install tox (if not already available):**
6494

65-
These steps are a guideline on how to add a new backend to python-can.
95+
.. tab:: Using uv
6696

67-
- Create a module (either a ``*.py`` or an entire subdirectory depending
68-
on the complexity) inside ``can.interfaces``
69-
- Implement the central part of the backend: the bus class that extends
70-
:class:`can.BusABC`.
71-
See :ref:`businternals` for more info on this one!
72-
- Register your backend bus class in ``BACKENDS`` in the file ``can.interfaces.__init__.py``.
73-
- Add docs where appropriate. At a minimum add to ``doc/interfaces.rst`` and add
74-
a new interface specific document in ``doc/interface/*``.
75-
It should document the supported platforms and also the hardware/software it requires.
76-
A small snippet of how to install the dependencies would also be useful to get people started without much friction.
77-
- Also, don't forget to document your classes, methods and function with docstrings.
78-
- Add tests in ``test/*`` where appropriate.
79-
To get started, have a look at ``back2back_test.py``:
80-
Simply add a test case like ``BasicTestSocketCan`` and some basic tests will be executed for the new interface.
97+
.. code-block:: shell
98+
99+
uv tool install tox --with tox-uv
100+
101+
.. tab:: Using pipx
102+
103+
.. code-block:: shell
104+
105+
pipx install tox
106+
107+
**Create a virtual environment and install python-can in editable mode**
108+
109+
.. tab:: Using uv
110+
111+
.. code-block:: shell
112+
113+
uv venv
114+
.venv\Scripts\activate # On Windows
115+
source .venv/bin/activate # On Unix/macOS
116+
uv pip install -e . --group dev
117+
118+
.. tab:: Using virtualenv and pip
119+
120+
.. code-block:: shell
121+
122+
python -m venv .venv
123+
.venv\Scripts\activate # On Windows
124+
source .venv/bin/activate # On Unix/macOS
125+
python -m pip --upgrade pip
126+
pip install -e . --group dev
127+
128+
3. **Make Your Changes**
129+
130+
* Edit code, documentation, or tests as needed.
131+
* If you fix a bug or add a feature, add or update tests in the ``test/`` directory.
132+
* If your change affects users, update documentation in ``doc/`` and relevant docstrings.
133+
134+
4. **Test Your Changes**
135+
136+
This project uses `tox <https://tox.wiki/en/latest/>`__ to automate all checks (tests, lint, type, docs).
137+
Tox will set up isolated environments and run the right tools for you.
138+
139+
To run all checks:
140+
141+
.. code-block:: shell
142+
143+
tox
144+
145+
To run a specific check, use:
146+
147+
.. code-block:: shell
148+
149+
tox -e lint # Run code style and lint checks (black, ruff, pylint)
150+
tox -e type # Run type checks (mypy)
151+
tox -e docs # Build and test documentation (sphinx)
152+
tox -e py # Run tests (pytest)
153+
154+
To run all checks in parallel (where supported), you can use:
155+
156+
.. code-block:: shell
157+
158+
tox p
159+
160+
Some environments require specific Python versions.
161+
If you use `uv`, it will automatically download and manage these for you.
162+
With `pipx`, you may need to install the required Python versions yourself.
163+
164+
5. **(Optional) Build Source Distribution and Wheels**
165+
166+
If you want to manually build the source distribution (sdist) and wheels for python-can,
167+
you can use either `uvx` or `pipx` to run the build and twine tools.
168+
Choose the method that best fits your workflow.
169+
170+
.. tab:: Using uvx
171+
172+
.. code-block:: shell
173+
174+
uvx --from build pyproject-build --installer uv
175+
uvx twine check --strict dist/*
176+
177+
.. tab:: Using pipx
178+
179+
.. code-block:: shell
180+
181+
pipx run build
182+
pipx run twine check dist/*
183+
184+
6. **Push and Submit Your Contribution**
185+
186+
* Push your branch:
187+
188+
.. code-block:: shell
189+
190+
git push origin my-feature-branch
191+
192+
* Open a pull request from your branch to the ``main`` branch of the main python-can repository on GitHub.
193+
194+
Please be patient — maintainers review contributions as time allows.
195+
196+
Creating a new interface/backend
197+
--------------------------------
81198

82199
.. attention::
83200
We strongly recommend using the :ref:`plugin interface` to extend python-can.
84201
Publish a python package that contains your :class:`can.BusABC` subclass and use
85202
it within the python-can API. We will mention your package inside this documentation
86203
and add it as an optional dependency.
87204

88-
Code Structure
89-
--------------
90-
91-
The modules in ``python-can`` are:
92-
93-
+---------------------------------+------------------------------------------------------+
94-
|Module | Description |
95-
+=================================+======================================================+
96-
|:doc:`interfaces <interfaces>` | Contains interface dependent code. |
97-
+---------------------------------+------------------------------------------------------+
98-
|:doc:`bus <bus>` | Contains the interface independent Bus object. |
99-
+---------------------------------+------------------------------------------------------+
100-
|:doc:`message <message>` | Contains the interface independent Message object. |
101-
+---------------------------------+------------------------------------------------------+
102-
|:doc:`io <file_io>` | Contains a range of file readers and writers. |
103-
+---------------------------------+------------------------------------------------------+
104-
|:doc:`broadcastmanager <bcm>` | Contains interface independent broadcast manager |
105-
| | code. |
106-
+---------------------------------+------------------------------------------------------+
205+
These steps are a guideline on how to add a new backend to python-can.
107206

207+
* Create a module (either a ``*.py`` or an entire subdirectory depending
208+
on the complexity) inside ``can.interfaces``. See ``can/interfaces/socketcan`` for a reference implementation.
209+
* Implement the central part of the backend: the bus class that extends
210+
:class:`can.BusABC`.
211+
See :ref:`businternals` for more info on this one!
212+
* Register your backend bus class in ``BACKENDS`` in the file ``can.interfaces.__init__.py``.
213+
* Add docs where appropriate. At a minimum add to ``doc/interfaces.rst`` and add
214+
a new interface specific document in ``doc/interface/*``.
215+
It should document the supported platforms and also the hardware/software it requires.
216+
A small snippet of how to install the dependencies would also be useful to get people started without much friction.
217+
* Also, don't forget to document your classes, methods and function with docstrings.
218+
* Add tests in ``test/*`` where appropriate. For example, see ``test/back2back_test.py`` and add a test case like ``BasicTestSocketCan`` for your new interface.
108219

109220
Creating a new Release
110221
----------------------
111222

112-
- Release from the ``main`` branch (except for pre-releases).
113-
- Check if any deprecations are pending.
114-
- Run all tests and examples against available hardware.
115-
- Update ``CONTRIBUTORS.txt`` with any new contributors.
116-
- For larger changes update ``doc/history.rst``.
117-
- Sanity check that documentation has stayed inline with code.
118-
- In a new virtual env check that the package can be installed with pip: ``pip install python-can==X.Y.Z``.
119-
- Create a new tag in the repository.
120-
- Check the release on
121-
`PyPi <https://pypi.org/project/python-can/#history>`__,
122-
`Read the Docs <https://readthedocs.org/projects/python-can/versions/>`__ and
123-
`GitHub <https://github.com/hardbyte/python-can/releases>`__.
124-
223+
* Releases are automated via GitHub Actions. To create a new release:
125224

126-
Manual release steps (deprecated)
127-
---------------------------------
225+
* Ensure all tests pass and documentation is up-to-date.
226+
* Update ``CONTRIBUTORS.txt`` with any new contributors.
227+
* For larger changes, update ``doc/history.rst``.
228+
* Create a new tag and GitHub release (e.g., ``vX.Y.Z``) targeting the ``main`` branch. Add release notes and publish.
229+
* The CI workflow will automatically build, check, and upload the release to PyPI and other platforms.
128230

129-
- Create a temporary virtual environment.
130-
- Create a new tag in the repository. Use `semantic versioning <http://semver.org>`__.
131-
- Build with ``pipx run build``
132-
- Sign the packages with gpg ``gpg --detach-sign -a dist/python_can-X.Y.Z-py3-none-any.whl``.
133-
- Upload with twine ``twine upload dist/python-can-X.Y.Z*``.
231+
* You can monitor the release status on:
232+
`PyPi <https://pypi.org/project/python-can/#history>`__,
233+
`Read the Docs <https://readthedocs.org/projects/python-can/versions/>`__ and
234+
`GitHub Releases <https://github.com/hardbyte/python-can/releases>`__.

‎doc/installation.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,13 @@ Install the ``can`` package from PyPi with ``pip`` or similar::
2121
$ pip install python-can[serial]
2222

2323

24+
Pre-releases
25+
------------
26+
27+
The latest pre-release can be installed with::
28+
29+
pip install --upgrade --pre python-can
30+
2431

2532
GNU/Linux dependencies
2633
----------------------

0 commit comments

Comments
 (0)