82a155d494
- CHANGELOG: new [Unreleased] section describing the vrcx feature set on top of the inherited 0.1.0 (bmccollect) baseline - CONTRIBUTING: dev/prod/old layout, full src/vrcx/ module tour, updated build/install commands, expanded 'where features go' table - ISSUE_TEMPLATE/config.yml: security advisories link points at vrcx
89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
# Contributing
|
|
|
|
> Project layout, build, and release flow. **If you only want to use the tool — read [README](README.md) instead.**
|
|
|
|
## Repo layout
|
|
|
|
```
|
|
vrcx/
|
|
├── .github/
|
|
│ ├── workflows/release.yml ← CI: tag-driven build + GitHub Release
|
|
│ └── ISSUE_TEMPLATE/ ← bug / feature / security routing
|
|
├── dev/ ← current work (everything code-related lives here)
|
|
│ ├── src/vrcx/
|
|
│ │ ├── __init__.py ← single source of truth for __version__
|
|
│ │ ├── __main__.py ← entry: python -m vrcx
|
|
│ │ ├── app.py ← orchestration: config, prompts, threads, packaging
|
|
│ │ ├── config.py ← config.ini next to the exe (first-run prompt)
|
|
│ │ ├── i18n.py ← EN/RU translation table + t() helper
|
|
│ │ ├── platform_win.py ← VT enable
|
|
│ │ ├── update_check.py ← GitHub /releases/latest poll (returns tag)
|
|
│ │ ├── commands.py ← BMC artefacts table
|
|
│ │ ├── bmc.py ← BmcSession (SSH + Redfish helper)
|
|
│ │ ├── collector.py ← per-host BMC collect loop
|
|
│ │ ├── os_commands.py ← SDS-host artefacts table
|
|
│ │ ├── sds.py ← SdsSession (SSH + sudo -S + SFTP)
|
|
│ │ ├── os_collector.py ← per-host OS collect loop
|
|
│ │ ├── discover.py ← Redfish-MAC → ARP → SDS IP
|
|
│ │ ├── tarball.py ← layout, per-host & session tar.gz
|
|
│ │ └── ui.py ← rich-based TUI
|
|
│ ├── assets/icon.ico ← embedded app icon
|
|
│ ├── tools/make_icon.ps1 ← regenerate the icon
|
|
│ ├── vrcx-launcher.py ← PyInstaller entry (absolute import)
|
|
│ ├── vrcx.spec ← PyInstaller spec (gitignored)
|
|
│ └── pyproject.toml
|
|
├── prod/ ← last stable portable build (gitignored)
|
|
├── old/ ← previous portable builds, kept for rollback
|
|
├── CHANGELOG.md / CONTRIBUTING.md / LICENSE / README.md / README.ru.md / SECURITY.md
|
|
└── .gitignore
|
|
```
|
|
|
|
`dev/` / `prod/` / `old/` is a workflow convention: new changes land in `dev/`, the validated build is copied into `prod/`, the previous `prod/` is archived under `old/`.
|
|
|
|
## Run from source
|
|
|
|
```
|
|
python -m pip install rich paramiko
|
|
PYTHONPATH=dev/src python -m vrcx
|
|
```
|
|
|
|
## Editable install
|
|
|
|
```
|
|
cd dev
|
|
python -m pip install -e .
|
|
vrcx
|
|
```
|
|
|
|
## Build the portable .exe
|
|
|
|
```
|
|
python -m pip install pyinstaller rich paramiko
|
|
python -m PyInstaller --onefile --console --name vrcx \
|
|
--icon dev/assets/icon.ico \
|
|
--paths dev/src dev/vrcx-launcher.py
|
|
```
|
|
|
|
## Cut a release
|
|
|
|
1. Bump `dev/src/vrcx/__init__.py` → `__version__ = "X.Y.Z"`.
|
|
2. Update `CHANGELOG.md` — move items from `[Unreleased]` into a new `[X.Y.Z]` section with today's date.
|
|
3. Commit: `git commit -am "vX.Y.Z: …"`.
|
|
4. Tag: `git tag vX.Y.Z`.
|
|
5. Push: `git push && git push --tags`.
|
|
|
|
CI builds the exe and creates the GitHub Release with the zip attached.
|
|
|
|
## Where features go
|
|
|
|
| Adding... | Touch this module |
|
|
|---|---|
|
|
| New BMC artefact | `commands.py` → one new `CommandSpec` row |
|
|
| New SDS-host artefact | `os_commands.py` → one new `OsCommandSpec` row |
|
|
| Support for a new BMC API (e.g. IPMI) | `bmc.py` → add a method on `BmcSession`; reference it from `commands.py` with a new `kind` |
|
|
| Different discovery strategy | `discover.py` |
|
|
| New per-host UI column / progress detail | `ui.py` → `Ui._render_table` + `set_progress` |
|
|
| Different output naming or layout | `tarball.py` |
|
|
| New configuration knob | `config.py` (add field + parser line) and use it from `app.py` |
|
|
| New translated string | `i18n.py` — add the key to both `en` and `ru` |
|
|
| Tweaking the startup banner / prompts | `app.py` → `main` / `_prompt_inputs` |
|