Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (82 loc) · 2.54 KB

CONTRIBUTING.md

File metadata and controls

118 lines (82 loc) · 2.54 KB
Raw

Contributing to Polaris

Thanks for your interest in contributing! This project is friendly to new contributors and first-time PRs. The goal is to keep the installer simple, reliable, and easy to audit.

Please make sure to follow our Code of Conduct in all project interactions.

How to contribute (issues first)

  1. Open an issue describing the bug, feature, or improvement.
  2. We'll discuss scope and approach.
  3. Submit a pull request once the plan is clear.

This helps avoid duplicated effort and keeps changes aligned with the project direction.

Development setup

There are no strict coding style requirements. Keep changes readable and focused.

Maintainer workflow: adding/editing apps

Polaris is intentionally data-driven.

Most app changes should be done in:

  • src/polaris (the FEATURES list)
  • src/polaris-helper (helper actions)

1) Add a new app/feature entry in FEATURES

Each item is a dict with keys like:

  • id (unique)
  • name
  • desc
  • check (installed-state rule)
  • install (list of helper action steps)
  • optional remove
  • optional contains (shown in in-app Details popup)

Example:

{
  "id": "mytool",
  "name": "🧰 My Tool",
  "desc": "Short description",
  "check": {"kind": "rpm", "pkg": "mytool"},
  "install": [["install_pkg", "mytool"]],
  "remove": [["remove_pkg", "mytool"]],
}

2) Pick the proper check kind

Current kinds:

  • rpm
  • rpm_all
  • flatpak
  • zram
  • repo_and_pkg
  • tailscale
  • pkg_and_service
  • appimage_glob
  • appimage_glob_any

If you need a new pattern, add it in _feature_applied().

3) Wire helper actions

Every action in install / remove must exist in src/polaris-helper dispatcher.

If missing, add:

  1. helper function
  2. case dispatcher entry

4) Validate before PR

python3 -m py_compile src/polaris
bash -n src/polaris-helper

Testing & building

Basic checks:

  • Launch the UI and verify the flow you changed.
  • Make sure logs show clean output.

Build the RPM locally (Fedora 43 example):

sudo dnf install -y rpm-build rpmdevtools rsync tar python3-pyside6 polkit
rpmdev-setuptree
./src/packaging/build-rpm.sh 1.0.0

Build artifacts are written to:

  • ~/rpmbuild/RPMS/noarch/polaris-<version>-1.fc43.noarch.rpm
  • ~/rpmbuild/SRPMS/polaris-<version>-1.fc43.src.rpm

Submitting a PR

  • Keep PRs small and focused when possible.
  • Explain what you changed and why.
  • Include screenshots for UI changes.

Questions

If you're unsure about anything, open an issue and ask — it's welcome.