Skip to content
This repository was archived by the owner on Mar 26, 2026. It is now read-only.

Commit 86503ad

Browse files
DefinetlyNotAIDefinetlyNotAI
committed
Add CONTRIBUTING.md: provide guidelines for contributing to the project
1 parent 3fc3652 commit 86503ad

1 file changed

Lines changed: 199 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Contributing to PyCTools
2+
3+
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.
4+
5+
## Code of Conduct
6+
7+
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
8+
9+
## Bug Reports and Feature Requests
10+
11+
If you encounter a bug or have a feature request, please open an issue on the [GitHub issue tracker](https://github.com/DefinetlyNotAI/PyCTools/issues).
12+
13+
- **Bug Reports**: Include detailed steps to reproduce, expected behavior, actual behavior, and environment details.
14+
- **Feature Requests**: Clearly describe the feature, its use case, and potential implementation approach.
15+
16+
## Development Workflow
17+
18+
1. Fork the repository
19+
2. Create a new branch (`git checkout -b feature/amazing-feature`)
20+
3. Make your changes
21+
4. Test your changes
22+
5. Commit your changes (`git commit -m 'Add amazing feature'`)
23+
6. Push to the branch (`git push origin feature/amazing-feature`)
24+
7. Open a Pull Request
25+
8. Wait for review and address any feedback
26+
9. When asked, make sure to upload the 3 required files for the release:
27+
- `dist.zip` - The compressed archive with DLL files
28+
- `dist.zip.sha256` - The hash verification file
29+
- The wheel file (e.g., `pyctools-0.2.0b0-py3-none-any.whl`)
30+
31+
## Coding Standards
32+
33+
- Follow PEP 8 style guidelines for Python code
34+
- Write comprehensive docstrings for all functions and classes
35+
- Include type hints where appropriate
36+
- Comment complex code sections
37+
38+
## Pull Request Process
39+
40+
1. Ensure your code works
41+
2. Update documentation as needed
42+
3. Wait for a maintainer approve your PR
43+
44+
## Release Process
45+
46+
Creating a new release of PyCTools involves several steps to ensure proper packaging and distribution.
47+
48+
### Pre-release Checklist
49+
50+
1. Update version in `pyCTools/__init__.py`
51+
2. Update documentation if needed
52+
3. Ensure running all distribution scripts and getting the required files ready for the release
53+
54+
### Building the Packages
55+
56+
1. Enter the `tool` directory:
57+
```powershell
58+
cd tool
59+
```
60+
61+
2. Run `compilerHelper.ps1` to compile the C code and generate the necessary DLL files inside `pyCTools`:
62+
```powershell
63+
.\compilerHelper.ps1
64+
```
65+
66+
3. This script will:
67+
- Compile the C code using MSVC
68+
- Generate the required DLL files in the `pyCTools/bin/` directory
69+
- Ensure that both x86 and x64 architectures are supported
70+
71+
4. Run the setupHelper.py script to build the wheel package:
72+
```powershell
73+
python setupHelper.py
74+
```
75+
76+
5. This process will:
77+
- Create the wheel file in the `dist/wheels` directory
78+
- Provide instructions for the next steps
79+
- Supply the assumed `pip` commands for both local and release use
80+
81+
6. Run the distributionHelper.ps1 PowerShell script to prepare release files:
82+
```powershell
83+
.\distributionHelper.ps1
84+
```
85+
86+
7. This script:
87+
- Copies DLL files with proper naming conventions from `pyCTools/bin/x64/` and `pyCTools/bin/x86/`
88+
- Creates dist.zip containing the binary files copied
89+
- Generates SHA256 hashes for verification
90+
91+
### Creating the GitHub Release
92+
93+
1. In the GitHub repository, go to "Releases" and click "Create a new release"
94+
95+
2. Use the version tag suggested by setupHelper.py (e.g., `1.0.0` or `0.2.0-beta`)
96+
- This is very important to ensure the release is properly versioned and the `pip` command works correctly.
97+
98+
3. Use the template from the [below](#release-notes-template) for the release description:
99+
- Fill in the version number
100+
- Add a descriptive title
101+
- List key highlights and changes
102+
- Include installation instructions
103+
104+
4. Upload the three required files (maintainers will ask you to upload these files to the PR):
105+
- `dist.zip` - The compressed archive with DLL files
106+
- `dist.zip.sha256` - The hash verification file
107+
- The wheel file (e.g., `pyctools-0.2.0b0-py3-none-any.whl`)
108+
109+
5. Publish the release
110+
111+
### Release Structure Requirements
112+
113+
The release structure must follow this format:
114+
115+
- The `dist.zip` file must contain:
116+
- `x64/` folder with 64-bit DLLs named `name_x64.dll`
117+
- `x86/` folder with 32-bit DLLs named `name_x86.dll`
118+
- The other generated files (if any) aren't of high importance but should be included for completeness
119+
- The wheel file must be unchanged and exactly as generated by the `setupHelper.py` script
120+
- Always include the `dist.zip.sha256` hash file for the `dist.zip` to ensure integrity
121+
122+
- The release notes must include:
123+
- Installation instructions with the correct pip command
124+
- Highlights of the changes
125+
- Important notes about DLL structure requirements
126+
- File descriptions table
127+
128+
> [!TIP]
129+
> Use the provided release notes template to ensure consistency and completeness in your release descriptions.
130+
131+
#### Release Notes Template
132+
133+
<details>
134+
<summary>Click to expand the template</summary>
135+
136+
```md
137+
# **pyCTools Release - {RELEASE_TITLE}**
138+
139+
---
140+
141+
### Installation of v{VERSION}
142+
Here is the pip command:
143+
144+
\`\`\`
145+
pip install https://github.com/DefinetlyNotAI/PyCTools/releases/download/{TAG_NAME}/{WHEEL_FILENAME}
146+
\`\`\`
147+
148+
---
149+
150+
{RELEASE_DESCRIPTION}
151+
152+
**Highlights:**
153+
154+
* **{HIGHLIGHT_1}:** {HIGHLIGHT_1_DESCRIPTION}
155+
* **{HIGHLIGHT_2}:** {HIGHLIGHT_2_DESCRIPTION}
156+
* **{HIGHLIGHT_3}:** {HIGHLIGHT_3_DESCRIPTION}
157+
* **{HIGHLIGHT_4}:** {HIGHLIGHT_4_DESCRIPTION}
158+
* **{HIGHLIGHT_5}:** {HIGHLIGHT_5_DESCRIPTION}
159+
160+
{ADDITIONAL_NOTES}
161+
162+
---
163+
164+
> [!IMPORTANT]
165+
> ## Attached will be a ZIP file that contains the built DLL's required by the python scripts,
166+
> YOU MUST keep the DLL structure the same: `dist/{architecture_type}/{name}_{architecture_type}.dll`
167+
>
168+
> 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
169+
>
170+
> 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
171+
>
172+
> You can place the `dist` folder in the same directory as the Python library.
173+
174+
> [!TIP]
175+
> 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.
176+
>
177+
> You can just check the source code of the `ps1` tool for the paths it checks for the files!
178+
179+
---
180+
181+
| File Name | Description | Notes |
182+
|--------------------|------------------------------------------------------|-----------------------------------------------------------------------|
183+
| `dist.zip` | Compressed archive containing required binaries | Uses ZIP compression. Contains all DLLs needed for the Python wrapper |
184+
| `dist.zip.sha256` | SHA-256 hash file for verifying `dist.zip` integrity | Ensure file hasn't been tampered with or corrupted |
185+
| `{WHEEL_FILENAME}` | WHL File for pip to install the library | Allows easy pip installation |
186+
187+
---
188+
189+
**Full Changelog**: https://github.com/DefinetlyNotAI/PyCTools/compare/{PREVIOUS_TAG}...{TAG_NAME}
190+
```
191+
192+
</details>
193+
194+
### Post-Release Tasks
195+
196+
1. Update documentation website if applicable
197+
2. Close related issues that were addressed in the release
198+
199+
---

0 commit comments

Comments
 (0)