Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (156 loc) · 7.51 KB

CONTRIBUTING.md

File metadata and controls

202 lines (156 loc) · 7.51 KB
Raw

Contributing to Cokpyt

Bug reports, feature ideas, documentation fixes and pull requests are all welcome.

Table of Contents

Code of Conduct

Be respectful. Everyone contributing here is doing so voluntarily. Constructive criticism is welcome; personal attacks are not.

Reporting Bugs

Check the Issues page first.

A useful report includes:

  1. OS and version
  2. Python version (python --version)
  3. pip version (pip --version)
  4. Cokpyt version (shown in Settings)
  5. Steps to reproduce
  6. What you expected, and what happened
  7. Console output — hit copy in the console header, or open Settings → View the log

Suggesting Features

Open an issue with a [Feature] prefix. Describe the problem you are trying to solve, and how the feature would address it. Screenshots and references to how other tools do it help.

Setting Up the Dev Environment

Prerequisites

Tool Version
Go 1.23 or later
Wails CLI v3
Node.js 20 or later (Vite 8)

Install the Wails v3 CLI:

go install github.com/wailsapp/wails/v3/cmd/wails3@latest

wails3 task deps installs the frontend's npm packages; wails3 build and wails3 dev do it for you.

Clone and run

git clone https://github.com/d3uceY/Cokpyt.git
cd Cokpyt

# Rebuild and rerun on every Go change
wails3 dev

Other commands you will want:

wails3 task test       # build the frontend, then go test ./...
wails3 task build      # regenerate bindings, build the frontend, then build Go
wails3 task run        # run the binary that is already built
wails3 task frontend   # Vite dev server on its own

Build a production binary

wails3 build       # current OS
wails3 package     # NSIS installer on Windows, .app bundle on macOS

Cross-compiling is a matter of setting GOOS and GOARCH. The Linux and macOS builds need CGO_ENABLED=1 and a platform toolchain; the Windows build does not.

Project Structure

Cokpyt/
  main.go                    -- Entry point: Wails options, window, service registration
  app.go                     -- The service the frontend calls; the whole API surface
  backend/
    environments/            -- Finds every Python environment on the machine
      env.go                 -- The Env type, and how a command runs against it
      discover.go            -- The launcher, install directories, and the marker sweep
    pip/                     -- Package operations, PyPI search, doctor, cleanup, history
    platform/                -- OS-specific process handling
  frontend/
    index.html               -- The Vite entry point
    vite.config.js           -- React plugin, dev-server port, asset layout
    package.json             -- React, Vite, and the two npm scripts
    src/
      main.jsx               -- Mounts the providers and the app
      App.jsx                -- Hash router, layout, and the page outlet
      api.js                 -- Wrapper over the generated bindings
      app/
        AppProvider.jsx      -- Environments, operation record, theme (useReducer)
        DataProvider.jsx     -- The cached, expensive reads
        DialogProvider.jsx   -- The one dialog that can be open
        ToastProvider.jsx    -- The toast list and its timers
        hooks.js             -- usePackages, useOutdated, useHistory, useRunning
        useResource.js       -- One async read, keyed and refetchable
        routes.js            -- The page table the sidebar and router share
      components/            -- Sidebar, page head, status bar, toasts, tables
      pages/                 -- One component per page
      ui/                    -- Design-system primitives
      lib/                   -- Pure helpers: formatting, environment, operations
      styles/app.css         -- The design system
    public/assets/           -- Fonts, logos, and the icon sprite
    bindings/                -- GENERATED by `wails3 generate bindings`. Do not edit.
    dist/                    -- GENERATED by `vite build`. Embedded by main.go.
  build/
    Taskfile.yml             -- Shared build steps; per-platform Taskfiles sit beside it
    config.yml               -- App metadata and dev-mode settings
  scripts/
    fetch-icons.ps1          -- Regenerates frontend/public/assets/icons.svg

A public method on App is callable from the frontend with no wiring beyond regenerating the bindings. Run wails3 task bindings, or just wails3 task compile, after changing Go signatures.

Making a Pull Request

  1. Fork the repo and create a branch from main: 
    git checkout -b fix/your-branch-name
  2. Make your changes and make sure the project still builds (wails3 build).
  3. If you changed frontend code, make sure it builds, and add or update a Go test for any non-trivial logic you touched: 
    wails3 task test   # builds the frontend, then runs go test ./...
  4. Commit with a message describing what changed and why.
  5. Push your branch and open a pull request against main, linking related issues.

Keep pull requests focused. One fix or feature per PR.

Style Guidelines

Go

  • Follow standard Go formatting. Run gofmt before committing.
  • Return errors, do not panic in library code.
  • Comments explain why, especially where a decision looks odd. Two examples worth reading before you touch them: why the discovery sweep has no depth limit, and why collapse folds launcher shims onto their target interpreter.
  • Non-trivial logic leaves one runnable check behind. Table-driven tests with real-world input are preferred over fixtures.

React

  • Function components and hooks. The only dependencies are React, Vite, and the plugin that compiles JSX; do not add a component library, a router, or a state manager for what is here.
  • User-supplied strings are rendered as text, never as markup.
  • State is React state. Anything shared lives in a provider under src/app/ and is read with a hook; there is no module-level mutable state and no manual subscription mechanism.
  • A page renders its own PageShell so its subtitle and actions can follow its state. Reads go through useResource (or the usePackages/useOutdated/useHistory hooks), which own loading, errors, and the refetch after an operation.
  • useEffect owns every side effect — the runtime event subscriptions, the timers, the fetches — and returns its cleanup, so StrictMode's double mount does not leave anything behind.
  • Comments explain why, in the same voice as the Go.

CSS

  • app.css is the design system. The rules are: square corners, 1px borders, uppercase micro-labels at 10px with wide tracking, one accent colour (#0048ad) that means "this is the action", and no decoration that does not carry information.
  • Everything is a token in :root. A dark value belongs in the [data-theme="dark"] block, not in a media query.
  • Do not introduce a UI library or an icon font. The icons are a ~11 KB SVG sprite; regenerate it with scripts/fetch-icons.ps1.

Questions?

Open an issue or a discussion on the GitHub repo.