Skip to content

Commit c06638c

Browse files
author
PyCompiler ARK++
committed
Refactor launcher scripts: update run.ps1 and run.sh to enhance functionality and improve user experience
1 parent 0c8a542 commit c06638c

3 files changed

Lines changed: 535 additions & 166 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Contributing Guide — PyCompiler ARK++
2+
3+
Thank you for your interest in contributing to PyCompiler ARK++! This guide explains how to get set up, the development workflow, quality standards, and how to submit changes effectively.
4+
5+
6+
## Table of Contents
7+
- Code of Conduct
8+
- Ways to Contribute
9+
- Getting Started (Environment Setup)
10+
- Development Workflow
11+
- Commit Messages (Conventional Commits)
12+
- Branching Strategy
13+
- Quality Standards (Lint, Format, Types, Security)
14+
- Tests and Coverage
15+
- Documentation Updates
16+
- Pull Request Checklist and Review
17+
- Issue Reporting and Feature Requests
18+
- Security Disclosures
19+
- Resources and Links
20+
21+
22+
## Code of Conduct
23+
Be respectful, inclusive, and professional in all interactions. We expect contributors to foster a welcoming environment. If you encounter unacceptable behavior, please report it to: ague.samuel27@gmail.com.
24+
25+
26+
## Ways to Contribute
27+
- Bug reports and reproduction cases
28+
- Feature requests and design proposals
29+
- Code contributions (features, fixes, refactors)
30+
- Tests (unit, integration, performance)
31+
- Documentation improvements (guides, examples, clarifications)
32+
33+
34+
## Getting Started (Environment Setup)
35+
36+
Prerequisites:
37+
- Python 3.10+ (3.11 recommended)
38+
- Git
39+
- A recent pip and virtualenv/venv
40+
41+
Clone and set up a virtual environment:
42+
```bash
43+
git clone https://github.com/raidos23/PyCompiler-ARK-Professional.git
44+
cd PyCompiler-ARK-Professional
45+
python -m venv .venv
46+
source .venv/bin/activate # Linux/macOS
47+
# or
48+
.venv\Scripts\activate # Windows
49+
50+
python -m pip install --upgrade pip
51+
pip install -r requirements.txt -c constraints.txt
52+
```
53+
Optional developer tooling:
54+
```bash
55+
# If you plan to run all quality checks locally
56+
python -m pip install ruff black mypy pytest bandit
57+
```
58+
59+
Run the application:
60+
```bash
61+
python main.py
62+
```
63+
64+
65+
## Development Workflow
66+
1) Create a feature branch from the active development branch:
67+
```bash
68+
git checkout -b feature/my-awesome-change origin/main
69+
# or from develop if that branch is used for active work
70+
```
71+
72+
2) Make focused, incremental commits (see Conventional Commits below).
73+
74+
3) Keep your branch up to date and rebase on the latest main when necessary:
75+
```bash
76+
git fetch origin
77+
git rebase origin/main
78+
```
79+
80+
4) Run quality checks and tests locally before opening a PR.
81+
82+
83+
## Commit Messages (Conventional Commits)
84+
Use the Conventional Commits format to create meaningful, machine-readable commit history:
85+
```
86+
<type>(<scope>): <short summary>
87+
88+
<body – optional>
89+
<footer – optional>
90+
```
91+
Common types:
92+
- feat: new feature
93+
- fix: bug fix
94+
- docs: documentation changes
95+
- style: formatting (no code behavior changes)
96+
- refactor: code changes that neither fix a bug nor add a feature
97+
- test: add or improve tests
98+
- chore: tooling, CI, maintenance
99+
100+
Examples:
101+
```
102+
feat(engine): add custom plugin discovery for Nuitka
103+
fix(ui): prevent crash when workspace folder is missing
104+
docs(sdk): clarify BC plugin metadata and tags
105+
```
106+
107+
108+
## Branching Strategy
109+
- main: stable, releasable state
110+
- develop (optional): active development branch
111+
- feature/*: features and improvements
112+
- fix/*: hotfixes and bug fixes
113+
114+
We recommend rebasing feature branches onto main (or develop) instead of merge commits to keep history linear.
115+
116+
117+
## Quality Standards (Lint, Format, Types, Security)
118+
Run the following before submitting a PR:
119+
```bash
120+
# Lint
121+
ruff check .
122+
# Format check
123+
black --check .
124+
# Static typing
125+
mypy .
126+
# Basic security scanning
127+
bandit -r .
128+
```
129+
130+
Notes:
131+
- Style is enforced via ruff (PEP8 + rules) and black (format)
132+
- Use explicit type hints for all public functions and classes
133+
- Avoid overly long functions; prefer small, testable units
134+
- Handle exceptions carefully and log user-facing errors clearly
135+
136+
137+
## Tests and Coverage
138+
Run tests (if a tests directory is present):
139+
```bash
140+
pytest -v --tb=short
141+
```
142+
For coverage (optional):
143+
```bash
144+
pytest --cov=Core --cov=Plugins_SDK --cov=engine_sdk --cov=bcasl
145+
```
146+
Guidelines:
147+
- Strive for meaningful coverage of critical paths
148+
- Add tests for new features and for bug fixes (to prevent regressions)
149+
150+
151+
## Documentation Updates
152+
Keep documentation in sync with code changes:
153+
- Update relevant guides in docs/
154+
- Ensure all references are accurate (no deprecated systems)
155+
- Prefer clear, concise English and runnable examples
156+
157+
Useful entry points:
158+
- docs/About_Sdks.md — overview of SDKs
159+
- docs/how_to_create_a_BC_plugin.md — BCASL plugin guide
160+
- docs/how_to_create_an_engine.md — engine development guide
161+
- SUPPORTED_MATRIX.md — supported OS/Python/engines
162+
163+
164+
## Pull Request Checklist and Review
165+
Before opening a PR:
166+
- [ ] Rebased on latest main (or develop)
167+
- [ ] Lint, format, types: clean (ruff, black, mypy)
168+
- [ ] Tests pass locally (pytest)
169+
- [ ] Documentation updated (if applicable)
170+
- [ ] Clear PR title and description (what, why, how)
171+
172+
Review focuses on:
173+
- Correctness and robustness
174+
- Readability and maintainability
175+
- Performance and security implications
176+
- Test coverage and documentation completeness
177+
178+
179+
## Issue Reporting and Feature Requests
180+
When opening an issue, provide:
181+
- Environment details (OS, Python, relevant versions)
182+
- Steps to reproduce
183+
- Expected vs actual behavior
184+
- Logs, stack traces, or screenshots where applicable
185+
186+
For features, describe the problem, propose a solution, and consider alternatives.
187+
188+
189+
## Security Disclosures
190+
If you discover a security vulnerability, please do not open a public issue. Email: ague.samuel27@gmail.com. We will coordinate a fix and disclosure process.
191+
192+
193+
## Resources and Links
194+
- Repository: https://github.com/raidos23/PyCompiler-ARK-Professional
195+
- Support Matrix: SUPPORTED_MATRIX.md
196+
- SDKs Overview: docs/About_Sdks.md
197+
- BC Plugin Guide: docs/how_to_create_a_BC_plugin.md
198+
- Engine Guide: docs/how_to_create_an_engine.md
199+
200+
201+
## License Notice
202+
By contributing, you agree that your contributions will be licensed under the project’s license (Apache-2.0).

0 commit comments

Comments
 (0)