Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
307 lines (205 loc) · 14.2 KB

CONTRIBUTING.md

File metadata and controls

307 lines (205 loc) · 14.2 KB

Contributing

This guide explains how to set up the development environment, understand the project architecture, and follow the code style.

Table of Contents

  1. Requirements
  2. Windows Support
  3. Installation
  4. Packaging
  5. Dependencies
  6. Testing
  7. Project Structure
  8. Contribution Process

Requirements

Windows Support

On Windows, use py instead of python3 for many of the examples in this documentation.

This package fully supports Windows, along with Linux and macOS, but Python is typically installed differently on Windows. Windows users typically access Python through the py launcher rather than a python3 link in their PATH. Within a virtual environment, all platforms operate the same and use a python link to access the Python version used in that virtual environment.

Installation

To install and run the program without a development environment, follow these instructions:

  1. Create and start the virtual environment (refer to the Virtual Environments section for more details):

    python3 -m venv venv
source venv/bin/activate

  2. Install the required dependencies:

    pip install -r requirements.txt

Packaging

This project is designed as a Python package, meaning it can be bundled and redistributed as a single compressed file.

Packaging is configured by:

  • setup.py
  • MANIFEST.in

Source Distribution

To package the project as a source distribution:

python3 setup.py sdist

This will generate dist/cryptosteganography-0.0.1.tar.gz.

(Note: The exact filename will vary based on the version number specified in setup.py.)

Dependencies

Dependencies are defined in:

  • requirements.in
  • requirements.txt
  • dev-requirements.in
  • dev-requirements.txt

Virtual Environments

It is best practice during development to create an isolated Python virtual environment using the venv standard library module. This will keep dependent Python packages from interfering with other Python projects on your system.

On Linux/macOS:

python3 -m venv venv
source venv/bin/activate

On Windows cmd:

py -m venv venv # Activate the virtual environment
venv\Scripts\activate.bat # On newer systems, you might only need to run 'venv\Scripts\activate' (without .bat)

Check if the terminal prompt changes to indicate the virtual environment is active (e.g., (venv) will appear in the terminal prompt)

Once activated, it is good practice to update pip to the latest version:

(venv)$ pip install --upgrade pip

Locking Dependencies

This project uses pip-tools to lock project dependencies and create reproducible virtual environments.

Note: Library projects should not lock their requirements.txt. Since cryptosteganography also has a CLI application, this end-user application example demonstrates how to lock application dependencies.

To update dependencies:

(venv)$ pip install pip-tools
(venv)$ pip-compile --output-file requirements.txt requirements.in
(venv)$ pip-compile --output-file dev-requirements.txt dev-requirements.in

Syncing Virtual Environments

After generating or updating the requirements files, sync them:

(venv)$ pip-sync requirements.txt dev-requirements.txt

After that run the unit tests as described in the Unit Testing section to ensure that the updates do not cause incompatibilities in the project.

Testing

Test Setup

Automated testing is performed using tox. Tox will automatically create virtual environments based on tox.ini for unit testing, PEP8 style guide checking, and documentation generation.

Running Tests

Install tox (only needed once):

python3 -m pip install tox

Run all environments:

tox #To run a specific environment, specify it like: -e pep8

Unit Testing

Unit testing is performed with pytest, a de facto standard Python unit testing framework. Some key advantages over the built-in unittest module are:

  1. Significantly less boilerplate needed for tests.
  2. PEP8 compliant names (e.g. pytest.raises() instead of self.assertRaises()).
  3. Vibrant ecosystem of plugins.

pytest will automatically discover and run tests by recursively searching for folders and .py files prefixed with test, as well as any functions prefixed by test.

The tests folder is created as a Python package (i.e., there is an __init__.py file within it) because this helps pytest uniquely namespace the test files. Without this, two test files cannot be named the same, even if they are in different sub-directories.

Code coverage is provided by the pytest-cov plugin.

When running a unit test tox environment (e.g., tox, tox -e py37, etc.), a data file (e.g., .coverage.py37) containing the coverage data is generated. This file is not readable on its own, but when the coverage tox environment is run (e.g., tox or tox -e coverage), coverage from all unit test environments is combined into a single data file. An HTML report is generated in the htmlcov folder, showing each source file and indicating which lines were executed during unit testing. Open htmlcov/index.html in a web browser to view the report. Code coverage reports help identify areas of the project that are not currently tested.

Code coverage is configured in the .coveragerc file.

Code Style Checking

PEP8 is the universally accepted style guide for Python code. PEP8 code compliance is verified using flake8. flake8 is configured in the [flake8] section of tox.ini. Three extra flake8 plugins are also included:

  • pep8-naming: Ensure functions, classes, and variables are named with correct casing.
  • flake8-quotes: Ensure that ' ' style string quoting is used consistently.
  • flake8-import-order: Ensure consistency in the way imports are grouped and sorted.

Project Structure

Traditional Layout

Traditionally, Python projects place the source for their packages in the root of the project structure:

root_folder
├── cryptosteganography
│   ├── __init__.py
│   ├── cli.py
│   └── lib.py
├── tests
│   ├── __init__.py
│   └── test_generate.py
├── tox.ini
└── setup.py

Issues with the Traditional Layout

However, this structure is known to have bad interactions with pytest and tox, which are standard tools for maintaining Python projects. The fundamental issue is that tox creates an isolated virtual environment for testing. By installing the distribution into the virtual environment, tox ensures that the tests pass even after the distribution has been packaged and installed, thereby catching any errors in packaging and installation scripts, which are common.

Having the Python packages in the project root subverts this isolation for two reasons:

  1. Sys.path Issues with pytest: Calling python in the project root (for example, python -m pytest tests/) causes Python to add the current working directory (the project root) to sys.path, which Python uses to find modules. Because the source package cryptosteganography is in the project root, it shadows the cryptosteganography package installed in the tox environment.
  2. Namespace Collisions: Calling pytest directly anywhere that it can find the tests will also add the project root to sys.path if the tests folder is a Python package (that is, it contains an __init__.py file). pytest adds all folders containing packages to sys.path because it imports the tests like regular Python modules.

Recommended Project Structure

To properly test the project, the source packages must not be on the Python path. To prevent this, there are three possible solutions:

  1. Remove the __init__.py file from tests and run pytest directly as a tox command.
  2. Remove the __init__.py file from tests and change the working directory of python -m pytest to tests.
  3. Move the Source Packages to a Dedicated src Folder.

The dedicated src directory is the recommended solution by pytest when using tox. This solution is promoted because it is the least brittle, even though it deviates from the traditional Python project structure. It results in a directory structure like:

root_folder
├── src
│   └── cryptosteganography
│       ├── __init__.py
│       ├── cli.py
│       └── lib.py
├── tests
│   ├── __init__.py
│   ├── test_cli.py
│   └── test_lib.py
├── tox.ini
└── setup.py

Benefits of the src Layout

  • Isolation: Ensures that the source code is not accidentally imported from the project root, preserving the isolation of the virtual environment.
  • Packaging Accuracy: Catches any errors in packaging and installation scripts early by installing the distribution into a controlled environment before testing.
  • Namespace Management: Minimizes the risk of namespace collisions, making it easier to manage and discover tests.

Adopting the src layout is considered best practice for maintaining a clean and manageable project structure.

Contribution Process

To contribute to cryptosteganography, follow these steps:

  1. Open an issue: If you find a bug or have a request, open an issue first to discuss what you would like to change.
  2. Fork the repository: Create your fork of the repository on GitHub.
  3. Create a feature branch: Make your changes in a feature branch (git checkout -b feature/FeatureName).
  4. Testing and linting: Run tests and ensure code style checks pass.
  5. Commit your changes: Write clear and concise commit messages.
  6. Sync your branch: Before pushing, make sure to pull the latest changes from the main branch and resolve any potential conflicts.
  7. Push the branch: Push your branch to your forked repository (git push origin feature/FeatureName).
  8. Create a pull request: Submit a pull request to merge your changes into the main branch.

We will review your pull request and provide feedback. Once approved, your changes will be merged. Thank you for your contributions!

Issue and Pull Request Templates

We have set up templates to streamline the process of reporting issues and submitting pull requests. These templates ensure that you provide all the necessary information, making it easier for maintainers and contributors to collaborate effectively.

Issue Templates

Our issue templates are located in the .github/ISSUE_TEMPLATE directory. When opening a new issue, you can choose from the following templates:

  • Bug Report: Use this template to report bugs. It helps you provide all necessary information to reproduce and fix the bug. The template includes sections for describing the bug, steps to reproduce, expected behavior, screenshots, and environment details.

    • Template File: .github/ISSUE_TEMPLATE/bug_report.md

  • Feature Request: Use this template to suggest new features or enhancements. It guides you in describing the problem, proposed solution, and any alternatives considered.

    • Template File: .github/ISSUE_TEMPLATE/feature_request.md

Pull Request Template

When submitting a pull request, please use the provided template. This ensures that you include all relevant information about the changes you are proposing, the testing done, and the impact on the project. The template includes checkboxes for you to confirm that you have followed the contribution guidelines.

  • Template File: .github/PULL_REQUEST_TEMPLATE.md

Continuous Integration Workflow

Our project uses GitHub Actions for continuous integration. The workflow is defined in the .github/workflows/python-package.yml file. This workflow runs on every push and pull request to the main and develop branches. It ensures that our codebase remains stable and meets quality standards across different Python versions (3.9, 3.10, 3.11, 3.12).

Workflow File: .github/workflows/python-package.yml

Workflow Details:

  • Name: Python Package CI

  • Triggers:

    • On push to main and develop branches
    • On pull request to main and develop branches

  • Jobs:

    • Build: Runs on ubuntu-latest
      • Matrix strategy to test multiple Python versions
      • Steps:
        1. Checkout the repository
        2. Set up Python
        3. Install dependencies
        4. Run tests using pytest, mypy, and flake8
        5. Generate documentation using sphinx
        6. Upload coverage to Codecov (for Python 3.9)

This setup ensures that all code changes are thoroughly tested and meet the project's standards before being merged.