Skip to content

Latest commit

 

History

History
199 lines (142 loc) · 7.23 KB

CONTRIBUTING.md

File metadata and controls

199 lines (142 loc) · 7.23 KB

Contributing to PyCTools

Thank you for your interest in contributing to PyCTools! This document provides guidelines for contributing to the project, including how to report bugs, suggest features, submit pull requests, and create releases.

Code of Conduct

Please read and follow our Code of Conduct.

Bug Reports and Feature Requests

If you encounter a bug or have a feature request, please open an issue on the GitHub issue tracker.

  • Bug Reports: Include detailed steps to reproduce, expected behavior, actual behavior, and environment details.
  • Feature Requests: Clearly describe the feature, its use case, and potential implementation approach.

Development Workflow

  1. Fork the repository
  2. Create a new branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Test your changes
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request
  8. Wait for review and address any feedback
  9. When asked, make sure to upload the 3 required files for the release:
    • dist.zip - The compressed archive with DLL files
    • dist.zip.sha256 - The hash verification file
    • The wheel file (e.g., pyctools-0.2.0b0-py3-none-any.whl)

Coding Standards

  • Follow PEP 8 style guidelines for Python code
  • Write comprehensive docstrings for all functions and classes
  • Include type hints where appropriate
  • Comment complex code sections

Pull Request Process

  1. Ensure your code works
  2. Update documentation as needed
  3. Wait for a maintainer approve your PR

Release Process

Creating a new release of PyCTools involves several steps to ensure proper packaging and distribution.

Pre-release Checklist

  1. Update version in pyCTools/__init__.py
  2. Update documentation if needed
  3. Ensure running all distribution scripts and getting the required files ready for the release

Building the Packages

  1. Enter the tool directory:

    cd tool

  2. Run compilerHelper.ps1 to compile the C code and generate the necessary DLL files inside pyCTools:

    .\compilerHelper.ps1

  3. This script will:

    • Compile the C code using MSVC
    • Generate the required DLL files in the pyCTools/bin/ directory
    • Ensure that both x86 and x64 architectures are supported

  4. Run the setupHelper.py script to build the wheel package:

    python setupHelper.py

  5. This process will:

    • Create the wheel file in the dist/wheels directory
    • Provide instructions for the next steps
    • Supply the assumed pip commands for both local and release use

  6. Run the distributionHelper.ps1 PowerShell script to prepare release files:

    .\distributionHelper.ps1

  7. This script:

    • Copies DLL files with proper naming conventions from pyCTools/bin/x64/ and pyCTools/bin/x86/
    • Creates dist.zip containing the binary files copied
    • Generates SHA256 hashes for verification

Creating the GitHub Release

  1. In the GitHub repository, go to "Releases" and click "Create a new release"

  2. Use the version tag suggested by setupHelper.py (e.g., 1.0.0 or 0.2.0-beta)

    • This is very important to ensure the release is properly versioned and the pip command works correctly.

  3. Use the template from the below for the release description:

    • Fill in the version number
    • Add a descriptive title
    • List key highlights and changes
    • Include installation instructions

  4. Upload the three required files (maintainers will ask you to upload these files to the PR):

    • dist.zip - The compressed archive with DLL files
    • dist.zip.sha256 - The hash verification file
    • The wheel file (e.g., pyctools-0.2.0b0-py3-none-any.whl)

  5. Publish the release

Release Structure Requirements

The release structure must follow this format:

  • The dist.zip file must contain:

    • x64/ folder with 64-bit DLLs named name_x64.dll
    • x86/ folder with 32-bit DLLs named name_x86.dll
    • The other generated files (if any) aren't of high importance but should be included for completeness

  • The wheel file must be unchanged and exactly as generated by the setupHelper.py script

  • Always include the dist.zip.sha256 hash file for the dist.zip to ensure integrity

  • The release notes must include:

    • Installation instructions with the correct pip command
    • Highlights of the changes
    • Important notes about DLL structure requirements
    • File descriptions table

Tip

Use the provided release notes template to ensure consistency and completeness in your release descriptions.

Release Notes Template

Click to expand the template 
# **pyCTools Release - {RELEASE_TITLE}**

---

### Installation of v{VERSION}
Here is the pip command:

\`\`\`
pip install https://github.com/DefinetlyNotAI/PyCTools/releases/download/{TAG_NAME}/{WHEEL_FILENAME}
\`\`\`

---

{RELEASE_DESCRIPTION}

**Highlights:**

* **{HIGHLIGHT_1}:** {HIGHLIGHT_1_DESCRIPTION}
* **{HIGHLIGHT_2}:** {HIGHLIGHT_2_DESCRIPTION}
* **{HIGHLIGHT_3}:** {HIGHLIGHT_3_DESCRIPTION}
* **{HIGHLIGHT_4}:** {HIGHLIGHT_4_DESCRIPTION}
* **{HIGHLIGHT_5}:** {HIGHLIGHT_5_DESCRIPTION}

{ADDITIONAL_NOTES}

---

> [!IMPORTANT]
> ## Attached will be a ZIP file that contains the built DLL's required by the python scripts,
> YOU MUST keep the DLL structure the same: `dist/{architecture_type}/{name}_{architecture_type}.dll`
>
> You will still find the other generated files if you want to play around with them, attached is also the ZIP's hash if you want to check the validity
>
> This supports Windows - both the `x86` (32-bit) and `x64` (64-bit) architecture, and the python wrappers also auto-detect the required architecture to use for your system, so as long as the dist is available, all is good
>
> You can place the `dist` folder in the same directory as the Python library.

> [!TIP]
> You can also just run the [`tool/compilerHelper.ps1`](https://github.com/DefinetlyNotAI/PyCTools/blob/main/tool/compilerHelper.ps1) tool where as long as you have the `cl.exe` from Microsoft Visual Studio `MSVC` toolchain.
>
> You can just check the source code of the `ps1` tool for the paths it checks for the files!

---

| File Name          | Description                                          | Notes                                                                 |
|--------------------|------------------------------------------------------|-----------------------------------------------------------------------|
| `dist.zip`         | Compressed archive containing required binaries      | Uses ZIP compression. Contains all DLLs needed for the Python wrapper |
| `dist.zip.sha256`  | SHA-256 hash file for verifying `dist.zip` integrity | Ensure file hasn't been tampered with or corrupted                    |
| `{WHEEL_FILENAME}` | WHL File for pip to install the library              | Allows easy pip installation                                          |

---

**Full Changelog**: https://github.com/DefinetlyNotAI/PyCTools/compare/{PREVIOUS_TAG}...{TAG_NAME}

Post-Release Tasks

  1. Update documentation website if applicable
  2. Close related issues that were addressed in the release