Skip to content

CONTRIBUTING.rst

Latest commit

 

History

History
112 lines (83 loc) · 4.23 KB

CONTRIBUTING.rst

File metadata and controls

112 lines (83 loc) · 4.23 KB
Raw

Contributing to elementpath

Contributions to the elementpath package are welcome! You can contribute by reporting bugs, improving documentation, or submitting pull requests for new features or bug fixes.

Reporting bugs

Please use the project's issue tracker to report bugs. When opening an issue, try to provide:

  • A clear description of the problem.
  • A minimal, self-contained example or test data that reproduces the issue.
  • Information about your environment (Python version, elementpath version, etc.).

Pull requests

If you want to contribute code, please keep in mind the project's goals:

  • The primary purpose of this package is to provide a base implementation of XPath.
  • Avoid adding features that are expensive to maintain.
  • Changes must not introduce backward incompatibilities. If a change to existing behavior is necessary, proposed modifications that introduce backward incompatibilities must remain inactive until the next major release, with only relevant deprecations or warnings being activated in the interim.
  • Code contributions should be prepared manually to ensure a full understanding of the changes. If you are unsure or if the change is complex, it is better to open an issue first to provide the specific case and start a discussion.

Please follow these steps:

  1. Fork the repository and create a new branch for your changes.
  2. Ensure your code follows the existing coding style and standards.
  3. Write or update tests to cover your changes.
  4. Verify that all tests pass using tox or by running the test suite manually.
  5. Submit a pull request with a clear description of your changes.

Development environment

To set up a development environment, you can install the package in editable mode with development dependencies:

pip install -e .[dev]

Alternatively, you can use the provided requirements-dev.txt file:

pip install -r requirements-dev.txt

Running tests

The project uses the standard unittest framework. You can run the tests manually using:

python -m unittest

It is recommended to use tox to run tests against all supported Python versions and to check code quality:

tox

As an alternative to standard methods, you can use the run_* scripts located in the tests/ directory. In particular, the tests/run_w3c_tests.py script allows running W3C XPath tests by specifying parameters and output verbosity. The W3C tests can be downloaded from the qt3tests repository. For example, to run tests with a specific catalog and increased verbosity:

python tests/run_w3c_tests.py --catalog path/to/qt3tests/catalog.xml -vv

Coding style

Code should follow the PEP 8 style guidelines. The project uses flake8 for linting and mypy for static type checking. You can run these checks via tox or directly:

flake8 elementpath tests
mypy --strict elementpath

AI Policy

The use of AI-assisted tools (such as LLMs) is permitted under the following strict conditions:

  • Scope: AI-generated contributions should be limited to the generation of tests. Code changes should be prepared manually to ensure you fully understand the logic and the impact of the changes. AI tools may be used for code analysis to help understand existing logic or identify potential issues.
  • No Large Rewrites: AI-generated or AI-inspired large-scale rewrites are rejected, as they are difficult to verify for correctness and may introduce subtle bugs.
  • No Error Suppression: AI-assisted contributions and annexed tests must avoid resolving problems using error and warning suppression methodologies.
  • Responsibility: The contributor remains fully responsible for the accuracy, correctness, and quality of the submitted code and tests.
  • Verification: All AI-assisted content must be manually reviewed, understood, and verified by the contributor.
  • Licensing: You must ensure that the AI-generated content does not violate any third-party intellectual property or licenses.

License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.