|
1 | | -# Contributing Guide |
2 | | - |
3 | | -This guide is meant to be directly usable by contributors working on PyCompiler ARK. |
4 | | - |
5 | | -## Setup |
6 | | - |
7 | | -```bash |
8 | | -git clone https://github.com/raidos23/PyCompiler_ARK.git |
9 | | -cd PyCompiler_ARK |
10 | | -python -m venv .venv |
11 | | -source .venv/bin/activate |
12 | | -pip install -r requirements.txt |
13 | | -``` |
14 | | - |
15 | | -On Windows: |
16 | | - |
17 | | -```bash |
18 | | -.venv\Scripts\activate |
19 | | -pip install -r requirements.txt |
20 | | -``` |
21 | | - |
22 | | -## Recommended workflow |
23 | | - |
24 | | -1. Create a branch from the active development branch. |
25 | | -2. Make a focused change set. |
26 | | -3. Run lint, tests, and smoke checks locally when relevant. |
27 | | -4. Update documentation when behavior changes. |
28 | | -5. Commit with a clear message describing the user-visible impact. |
29 | | - |
30 | | -## Local checks |
31 | | - |
32 | | -Baseline checks: |
33 | | - |
34 | | -```bash |
35 | | -ruff check . |
36 | | -black --check . |
37 | | -pytest -q tests |
38 | | -python -m py_compile pycompiler_ark.py |
39 | | -``` |
40 | | - |
41 | | -Useful smoke commands: |
42 | | - |
43 | | -```bash |
44 | | -python -m pycompiler_ark --help |
45 | | -python -m pycompiler_ark --version |
46 | | -python -m pycompiler_ark --info |
47 | | -python -m pycompiler_ark engine list --json |
48 | | -python -m pycompiler_ark workspace inspect . --json |
49 | | -python -m pycompiler_ark doctor --json |
50 | | -python -m pycompiler_ark check /path/to/workspace --json |
51 | | -python -m pycompiler_ark --cli |
52 | | -``` |
53 | | - |
54 | | -For reliable prechecks, point `check --strict` at a workspace that already |
55 | | -defines an entrypoint in `ark.yml`. |
56 | | - |
57 | | -Release-oriented checks should follow the CLI examples in this guide and the README. |
58 | | -For publishing steps, follow [`docs/release_process.md`](./release_process.md). |
59 | | - |
60 | | -## Where to make changes |
61 | | - |
62 | | -- CLI behavior: `Ui/Cli/` |
63 | | -- headless discovery and payload helpers: `Ui/Cli/discovery.py` |
64 | | -- classic GUI wiring: `Core/UiConnection.py` |
65 | | -- IDE-like GUI wiring: `Core/IdeLikeGui/` |
66 | | -- compilation logic: `Core/Compiler/` |
67 | | -- environment and dependency logic: `Core/Venv_Manager/`, `Core/deps_analyser/` |
68 | | -- built-in engines: `ENGINES/` |
69 | | -- BCASL plugins and runtime: `Plugins/`, `bcasl/`, `Plugins_SDK/` |
70 | | -- documentation: `docs/` |
71 | | - |
72 | | -## Contribution rules of thumb |
73 | | - |
74 | | -- Prefer extending existing shared helpers over copying logic. |
75 | | -- Keep UI-specific code thin. |
76 | | -- Keep engine-specific behavior inside engines. |
77 | | -- Treat i18n as shared architecture, not as per-widget local logic. |
78 | | -- Add or update tests when changing heuristics, parsing, or orchestration behavior. |
79 | | -- If you change CLI flags, commands, or docs-linked behavior, update the README. |
80 | | -- If you change the command hierarchy (`gui`, `engine`, `workspace`, `init`, `config-auto`, `check`, `scaffold`) or JSON outputs, update the CLI docs. |
81 | | -- Keep CI-facing exit codes stable, or document the change explicitly in the README. |
82 | | -- For CI/CD behavior, keep [`docs/ci_cd_ark_cli.md`](./ci_cd_ark_cli.md) as the single source of truth and align other docs/examples to it. |
83 | | -- For GUI behavior that impacts CI expectations (entrypoint, workspace persistence, engine config), explicitly state whether behavior is temporary session state or persisted workspace state. |
84 | | -- If you change IDE/classic behavior, update the IDE docs when appropriate. |
85 | | -- If you change translated GUI behavior, follow [`docs/dev_docs/i18n_ark.md`](./dev_docs/i18n_ark.md) and keep classic/IDE wiring aligned. |
86 | | - |
87 | | -## i18n architecture rule |
88 | | - |
89 | | -ARK has a specific i18n architecture and contributors should follow it instead of |
90 | | -adding local ad-hoc translation code. |
91 | | - |
92 | | -- Add keys in `languages/*.json`. |
93 | | -- Map widgets first, then wire shared GUI translations in `Core/i18n.py`. |
94 | | -- Reuse classic GUI translation flow when exposing the same feature in IDE-like GUI. |
95 | | -- For IDE proxy controls such as the `(...)` menu, prefer reusing existing translated classic controls or the active `self._tr` table instead of hardcoding new strings. |
96 | | -- Test language switching live, without restarting the app. |
97 | | -- Use [`docs/dev_docs/i18n_ark.md`](./dev_docs/i18n_ark.md) as the reference integration guide. |
98 | | - |
99 | | -## Documentation expectations |
100 | | - |
101 | | -Contributors should update documentation when they modify: |
102 | | - |
103 | | -- public CLI behavior |
104 | | -- workflow or release steps |
105 | | -- architecture-relevant module boundaries |
106 | | -- dependency analyzer heuristics |
107 | | -- IDE/classic parity behavior |
108 | | - |
109 | | -## Good first doc touchpoints |
110 | | - |
111 | | -- [Release process](./release_process.md) |
112 | | -- [Architecture overview](./architecture.md) |
113 | | -- [Dependency analyzer](./dependency_analyzer.md) |
114 | | -- [Dedicated CLI](./dedicated_cli.md) |
115 | | -- [ARK i18n architecture](./dev_docs/i18n_ark.md) |
0 commit comments