Contribution Guidelines & AI Policy
Relevant source files
The following files were used as context for generating this wiki page:
Parashell, as a fork of FreeCAD, adheres to the FreeCAD Contribution Process (FCP). The primary objective of these guidelines is to provide a transparent, fair, and efficient environment for contributors to resolve problems and improve the software's quality. The process is heavily influenced by the Collective Code Construction Contract and the GitHub Fork and Pull model.
Sources: CONTRIBUTING.md:1-12
1. Governance and Roles
The project operates under a defined hierarchy to manage contributions and maintain infrastructure. The process is designed to minimize dependence on individuals by encouraging a large pool of active participants.
Defined Roles
| Role | Description |
|---|---|
| User | A member of the community who uses the software. |
| Contributor | Someone who submits code changes to resolve identified problems. |
| Maintainer | An individual with commit access who enforces the process and merges contributions. |
| Administrator | "Owners" of the GitHub organization who manage maintainers and infrastructure. |
Sources: CONTRIBUTING.md:46-60, CONTRIBUTING.md:118-125
Governance Workflow
The following diagram illustrates the relationship between these roles and the contribution lifecycle:
Sources: CONTRIBUTING.md:46-60, CONTRIBUTING.md:126-140
2. Technical Submission Requirements
All contributions must be submitted via GitHub Pull Requests (PR). A "Valid PR" is defined by several strict technical and procedural criteria to ensure codebase stability.
- Atomic Changes: A PR should be a minimal and accurate solution to exactly one identified problem.
- Compile Stability: Each commit in a PR must compile cleanly. Checkpoint commits should be squashed before merging.
- Platform Support: Changes must pass self-tests on all target platforms and build against the "main" branch.
- Licensing: Contributions must be compatible with LGPL2+ and authors must provide assurance against copyright infringement.
Sources: CONTRIBUTING.md:68-100, src/3rdParty/libE57Format/CONTRIBUTING.md:20-24
3. Coding Conventions
The project enforces specific style guidelines to maintain readability across its Python and C++ components.
Python Guidelines
- Standards: Compliance with PEP 8 (style) and PEP 257 (docstrings) is required.
- Line Length: Python code should generally not exceed 80 to 100 characters per line.
- Formatting: Use 4 spaces for indentation (no tabs) and Unix line endings (LF).
- Imports: Must be grouped by standard library, third-party, and FreeCAD-specific modules. Alphabetical sorting within groups is recommended to reduce merge conflicts.
Sources: src/Mod/Draft/coding_conventions.md:20-45, src/Mod/Fem/coding_conventions.md:38-65
Naming Policy
| Element | Convention | Example |
|---|---|---|
| Modules | snake_case | draft_tools.py |
| Classes | CamelCase | DraftManager |
| Variables | snake_case | item_count |
| Constants | ALL_CAPS | MAX_ITERATIONS |
| Internal | Leading Underscore | _internal_method() |
Sources: src/Mod/Draft/coding_conventions.md:58-75, src/Mod/Fem/coding_conventions.md:75-81
4. AI Policy
Parashell enforces a human-centric approach to software development as outlined in the AI Policy.
- Assistive Only: AI may only be used in an assistive capacity.
- Human Oversight: Humans must remain "in the driver seat," meaning every contribution must be fully understood by the human contributor.
- Communication: All project communications must be conducted by people, not AI agents.
Sources: CONTRIBUTING.md:95-99
5. Code of Conduct and Enforcement
The community is expected to "be excellent to each other," adhering to principles of respect, consideration, and forgiveness.
Enforcement Mechanism
Maintainers are responsible for clarifying standards and taking corrective action against unacceptable behavior, including:
- Editing/Removing: Comments, commits, or wiki edits not aligned with the code.
- Banning: Temporary or permanent removal of contributors for harmful behavior.
- Confidentiality: All reports of abuse are investigated with reporter confidentiality maintained.
Sources: CODE_OF_CONDUCT.md:1-40
6. Development Priorities
When reviewing Pull Requests, maintainers prioritize work based on the impact on project stability and the shared roadmap.
Sources: src/Mod/CAM/Roadmap/README.md:65-85
7. Tooling for Contributors
Contributors are encouraged to use automated tools to ensure compliance before submission.
- Formatting:
clang-formatis used for C++ (e.g., targete57-clang-format). - Linting:
flake8is used for Python, often ignoring specific codes like E226 and W503. - Spelling:
codespellis utilized to catch typos in documentation and source comments.
Sources: src/Mod/Draft/coding_conventions.md:88-100, src/Mod/Fem/coding_conventions.md:12-25, src/3rdParty/libE57Format/CONTRIBUTING.md:29-35
Summary
Contributing to Parashell requires adherence to the FreeCAD Contribution Process, emphasizing human-driven development, strict coding standards (PEP 8 for Python, CamelCase for C++), and a respectful community environment. PRs are evaluated based on their adherence to technical requirements, licensing compatibility, and alignment with the project's development roadmap.