Skip to content

Commit e0fc357

Browse files
pennersrpennersr
committed
docs: added CONTRIBUTING
Squashed commit of the following: commit 66d7a47579de87b2e0a7f491bf6d8b66babd5efe Author: Huy Nguyen <danghuy1999@gmail.com> Date: Sun May 18 10:05:18 2025 +0700 docs(contributing): convert from MD to RST with include markers and update isort command commit f30eb7dbf0b2d025fceeae7deb54dbeaa276763a Author: Huy Nguyen <danghuy1999@gmail.com> Date: Thu May 8 17:24:39 2025 +0700 docs(contributing): add CONTRIBUTING.md and update project docs
1 parent cae1227 commit e0fc357

File tree

7 files changed

+274
-14
lines changed

7 files changed

+274
-14
lines changed

‎CONTRIBUTING.rst

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
Contributing to django-allauth
2+
==============================
3+
4+
.. begin-contributing
5+
6+
Thank you for considering contributing to django-allauth! This document outlines the process for contributing to the project and sets up your development environment.
7+
8+
Code of Conduct
9+
---------------
10+
11+
In the interest of fostering an open and welcoming community, we as contributors and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
12+
13+
Getting Started
14+
---------------
15+
16+
Setting Up Your Development Environment
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
There are two primary ways to set up your development environment:
20+
21+
Option 1: Standard Python Virtual Environment (Recommended for Beginners)
22+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23+
24+
1. **Install system dependencies**
25+
26+
Before creating a virtual environment, you'll need to install some system dependencies:
27+
28+
**On macOS:**
29+
30+
.. code-block:: bash
31+
32+
# Using Homebrew
33+
brew install libxml2 libxmlsec1 pkg-config openssl
34+
35+
**On Ubuntu/Debian:**
36+
37+
.. code-block:: bash
38+
39+
sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl pkg-config
40+
41+
**On RHEL/CentOS/Fedora:**
42+
43+
.. code-block:: bash
44+
45+
sudo dnf install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel
46+
47+
2. **Create and activate a virtual environment**
48+
49+
.. code-block:: bash
50+
51+
# Create a virtual environment
52+
python -m venv virtualenv
53+
54+
# Activate it
55+
# On Windows:
56+
virtualenv\Scripts\activate
57+
# On macOS/Linux:
58+
source virtualenv/bin/activate
59+
60+
3. **Install django-allauth in development mode**
61+
62+
.. code-block:: bash
63+
64+
# Install development dependencies
65+
pip install -r requirements-dev.txt
66+
67+
Option 2: Using Nix (Recommended for Advanced Users)
68+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
69+
70+
If you prefer a more isolated and reproducible development environment, you can use Nix:
71+
72+
1. **Install Nix** (If you don't have it already)
73+
74+
Follow the `official installation instructions <https://nixos.org/download.html>`_.
75+
76+
2. **Launch the Nix shell**
77+
78+
.. code-block:: bash
79+
80+
# This will create an isolated environment with all required dependencies
81+
nix-shell
82+
83+
Note: The first time you run this command, it may take a significant amount of time as it builds all dependencies. Subsequent launches will be much faster.
84+
85+
For faster startup, you can use:
86+
87+
.. code-block:: bash
88+
89+
nix-shell --arg doCheck false
90+
91+
Running Tests
92+
-------------
93+
94+
django-allauth uses a comprehensive test suite. You can run tests in several ways:
95+
96+
Using pytest directly
97+
~~~~~~~~~~~~~~~~~~~~~
98+
99+
.. code-block:: bash
100+
101+
# Run all tests for the default setup
102+
pytest allauth/
103+
104+
# Run tests with a specific Django settings module
105+
pytest --ds=tests.regular.settings allauth/
106+
107+
# Run a specific test file
108+
pytest allauth/account/tests/test_login.py
109+
110+
Note, if you are using MacOS, using pip and get this error when run tests:
111+
112+
.. code-block:: bash
113+
114+
import xmlsec
115+
ImportError: dlopen( ... symbol not found in flat namespace '_xmlSecOpenSSLTransformHmacRipemd160GetKlass')
116+
117+
You can try:
118+
119+
.. code-block:: bash
120+
121+
pip uninstall xmlsec lxml
122+
pip install --no-binary :all: xmlsec
123+
# Ref: https://github.com/xmlsec/python-xmlsec/issues/320
124+
125+
Using nox (recommended)
126+
~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
Nox automates testing across different Python and Django versions:
129+
130+
.. code-block:: bash
131+
132+
# List all available sessions
133+
nox --list
134+
135+
# Run tests for a specific Python version
136+
nox -x --session "test-3.11"
137+
138+
# Run tests for specific environment
139+
nox -x --session "test-3.11" --python 3.11 -- --ds=tests.regular.settings allauth/account/tests/test_login.py
140+
141+
Run Code Quality Checks
142+
~~~~~~~~~~~~~~~~~~~~~~~
143+
144+
.. code-block:: bash
145+
146+
# Run all linting checks
147+
nox -t lint
148+
149+
# Run specific check
150+
nox --session black
151+
nox --session isort
152+
nox --session flake8
153+
nox --session mypy
154+
nox --session bandit
155+
nox --session djlint
156+
157+
Building Documentation
158+
----------------------
159+
160+
Documentation is built using Sphinx:
161+
162+
.. code-block:: bash
163+
164+
# Build the documentation
165+
nox --session docs
166+
167+
The built documentation will be available in the ``docs/_build/html`` directory.
168+
169+
Development Workflow
170+
--------------------
171+
172+
1. **Create a new branch for your feature or bugfix**
173+
174+
.. code-block:: bash
175+
176+
git checkout -b feature/your-feature-name
177+
178+
2. **Make your changes and add tests**
179+
180+
All new features should include proper tests.
181+
182+
3. **Run tests locally to ensure everything passes**
183+
184+
.. code-block:: bash
185+
186+
nox -x --session "test-3.11"
187+
188+
4. **Run code quality checks**
189+
190+
.. code-block:: bash
191+
192+
nox -t lint
193+
194+
5. **Commit your changes with meaningful commit messages**
195+
196+
6. **Submit a pull request to the main repository**
197+
198+
Pull Request Guidelines
199+
-----------------------
200+
201+
- Update documentation for significant changes
202+
- Add tests for new functionality
203+
- Ensure all tests pass
204+
- Follow the project's code style
205+
- Keep pull requests focused on a single topic
206+
- Write clear, descriptive commit messages
207+
208+
Additional Resources
209+
--------------------
210+
211+
- `Official Documentation <https://docs.allauth.org/en/latest/>`_
212+
- `Issue Tracker <https://codeberg.org/allauth/django-allauth/issues>`_
213+
- `Project Source <https://codeberg.org/allauth/django-allauth>`_
214+
215+
Thank you for your contributions!
216+
217+
.. end-contributing

‎docs/project/contributing.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Contributing
2+
============
3+
4+
.. include:: ../../CONTRIBUTING.rst
5+
:start-after: .. begin-contributing
6+
:end-before: .. end-contributing

‎docs/project/funding.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Funding
2+
-------
3+
4+
Maintaining a project of this nature to align with the latest standards and
5+
expectations demands a significant investment of time and effort. If you are
6+
using this project, especially in a commercial context, then please do consider
7+
`sponsoring <https://github.com/sponsors/pennersr>`_.

‎docs/project/index.rst

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,8 @@
11
Project
22
=======
33

4-
Commercial Support
5-
------------------
4+
.. toctree::
65

7-
.. include:: ../../README.rst
8-
:start-after: .. begin-support
9-
:end-before: .. end-support
10-
11-
Funding
12-
-------
13-
14-
Maintaining a project of this nature to align with the latest standards and
15-
expectations demands a significant investment of time and effort. If you are
16-
using this project, especially in a commercial context, then please do consider
17-
`sponsoring <https://github.com/sponsors/pennersr>`_.
6+
support
7+
funding
8+
contributing

‎docs/project/support.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Commercial Support
2+
------------------
3+
4+
.. include:: ../../README.rst
5+
:start-after: .. begin-support
6+
:end-before: .. end-support

‎noxfile.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ def lint(session):
2323
@nox.session(tags=["lint"])
2424
def isort(session):
2525
session.install("isort==5.13.2")
26-
session.run("isort", "--check-only", "--diff", ".")
26+
session.run("isort", "--check-only", "--diff", "--gitignore", ".")
2727

2828

2929
@nox.session(tags=["lint"])

‎requirements-dev.txt

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Install the package itself with all extras
2+
-e ".[mfa,openid,steam,socialaccount]"
3+
4+
# Core packages
5+
Django>=4.2.16
6+
Sphinx
7+
sphinx_rtd_theme
8+
9+
# Testing tools
10+
pytest>=7.4
11+
pytest-asyncio==0.23.8
12+
pytest-django>=4.5.2
13+
pytest-cov
14+
15+
# Code quality
16+
isort==5.13.2
17+
bandit==1.7.10
18+
black==24.4.0
19+
djlint==1.34.1
20+
flake8==6.0.0
21+
mypy==1.10.0
22+
23+
# Type stubs
24+
django-stubs==5.0.2
25+
types-requests==2.32.0.20240602
26+
27+
# Additional dependencies
28+
Pillow>=9.0
29+
psycopg2-binary>=2.9.10,<3
30+
djangorestframework>=3.15.2,<4
31+
django-ninja>=1.3.0,<2
32+
pyyaml>=6.0.2,<7
33+
nox

0 commit comments

Comments
 (0)