Skip to content

Home

Jump to bottom
Joel B edited this page May 5, 2026 · 31 revisions

Welcome to the pynventory wiki / developer handbook!

Everything you need to set up, write code, and contribute to this project.

1. Prerequisites

Make sure these are installed on your machine:

  • Python 3.8 or newer
  • Git

Check with:

python --version
git --version

2. Development environment setup

Why do we use virtual environments and what are they?

2.1 Create a virtual environment in project root folder

python -m venv .venv

OR if you get an error message:

python3 -m venv .venv

This creates a .venv folder in the project root. It is already in .gitignore so it will never be committed.

2.2 Allow activation of virtual environments (Windows only)

Run PowerShell as admin and enter:

set-executionpolicy remotesigned

2.3 Activate the virtual environment

Linux / macOS:

source .venv/bin/activate

Windows (Command Prompt):

.venv\Scripts\activate

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Your terminal should now show (.venv) before the prompt. That means it is active.

2.4 Install dependencies

Click here to read about dependencies

Install the project's development tools:

pip install -r requirements.txt

Currently this only includes Ruff, the formatter and linter. The project itself uses only the Python standard library.

3. Git workflow — full tutorial

This walks you through the full process, from cloning to having your code merged. If you already know git, skip ahead to the quick reference.

NOTE:

  • master branch is the main "production" version
  • development happens from development branch on individual branches
  • create a branch before you make changes
  • changes from your branch get merged to development, development gets merged to master once release happens

3.1 If you do not have the repository yet, clone the repository

git clone https://github.com/blomma-dev/pynventory.git
cd pynventory

3.2 Branch guide

The main branch of the repository is master.

Development work takes place from development.

git checkout master
git pull origin master
git checkout development
git pull origin development

Always start new work from an up-to-date development.

git fetch
git pull

Useful commands

git status

3.3 Create a branch

Name it after what you are doing. Use one of the prefixes below:

  • feature/ — new functionality
  • fix/ — bug fixes
  • chore/ — cleanup, refactoring, docs

Examples:

git checkout -b feature/search-by-name
git checkout -b fix/delete-confirmation
git checkout -b chore/refactor-functions

3.4 Your work

Write code, test it manually, and commit as you go. Commit often with clear messages. You can use either VScode git, git through terminal or for example GitHub desktop. Whatever works for you.

3.5 Stage and commit

git add main.py (or whatever your modified file is named)
git commit -m "add search command"

Or stage everything:

git add .
git commit -m "add search command with partial name matching"

More on commit messages in section 6.

3.6 Keep your branch up to date

If someone merged something to master or development while you were working:

git checkout master
git pull origin master
git checkout your-branch
git merge master

OR

git checkout development
git pull origin development
git checkout your-branch
git merge development

Fix any conflicts, then commit the merge.

3.7 Push your branch

git push origin your-branch

3.8 Open a pull request

Go to the repository on GitHub. You will see a banner suggesting you open a pull request for your recently pushed branch. Click it.

ALWAYS SELECT DEVELOP TO RECEIVE CHANGES FROM YOUR BRANCH

Fill in the description (see section 8) and make sure to select a reviewer for the PR. Once ready, click submit.

3.9 Address review feedback

If the reviewer requests changes, make them on the same branch, commit, and push again. The pull request updates automatically.

3.10 Done

Once a pull request is approved it can be merged by the maintainer (most likely you if you are reading this), and then your branch can be deleted. GitHub offers a button for this right on the merged PR page. IMPORTANT: Do not attempt to delete development or master branches

Locally, switch back to master and pull:

git checkout master
git pull origin master

OR

git checkout development
git pull origin development

4. Git workflow — quick reference

Read below more about branches

Why we use branches?

# Start fresh
git checkout master
git pull origin master

# Start from development
git checkout development
git pull origin development

# Branch and work
git checkout -b feature/your-thing
# ... write code ...
git add .
git commit -m "what you did"

# Push and PR
git push origin feature/your-thing
# ... open pull request on GitHub ...

# After merge
git checkout master
git pull origin master

OR

git checkout development
git pull origin development

5. Branch naming

Stick to these prefixes so anyone can tell what a branch is for at a glance:

Prefix Use for
feature/ New functionality
fix/ Bug fixes
chore/ Refactoring, cleanup, docs

Keep the name short and descriptive. Lowercase, hyphens for spaces.

Good:

  • feature/search-by-brand
  • fix/empty-name-crash
  • chore/split-functions-file

Bad:

  • mybranch
  • stuff
  • FeatureSearchByBrand

6. Commit messages

6.1 Format

A good commit message has:

  • A short subject line (50 characters or less).
  • Written in the imperative mood: "add search" not "added search" or "adds search".
  • A blank line, then a longer description if the change needs explaining.

6.2 Examples

add search command with partial name matching

fix crash when deleting a product that does not exist

The program would raise an IndexError if you tried to
delete an ID that was not in the table. Now it checks
first and shows a clear message.

6.3 What to avoid

  • Vague messages like "update code" or "fix bug".
  • Messages longer than 50 characters for the subject.
  • Messages in past tense.

7. Code style

7.1 Formatter

We use Ruff for formatting and linting. It is fast, minimal, and the built-in formatter in Zed. VSCode users can install the Ruff extension.

Install Ruff:

pip install -r requirements.txt

Or directly:

pip install ruff

7.2 Using Ruff

Format your code:

ruff format .

Check for issues:

ruff check .

Fix issues automatically:

ruff check --fix .

7.3 Editor setup

VSCode — Install the Ruff extension and add this to your settings:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

Zed — Ruff is the default formatter for Python. No setup needed.

PyCharm — Install the Ruff plugin:

  1. Go to Settings → Plugins and search for "Ruff".
  2. Install and restart PyCharm.
  3. Go to Settings → Tools → Ruff.
  4. Check Enabled and set Run on save to true.
  5. PyCharm will auto-detect the project's ruff.toml.

The project's ruff.toml file keeps formatting the same across all editors.

7.4 Consistency

Look at what is already in the project and follow the same patterns:

  • How functions are named: snake_case
  • How classes are named: PascalCase
  • How indentation works: 4 spaces
  • How input validation is structured

When you add new code, match what is around it.

7.5 Comments

Code should explain itself most of the time. Add a comment only when something is not obvious at first glance. Keep them short.

Avoid leaving commented-out code. If it is not used, delete it.

8. Pull request expectations

Click here to read about pull requests

When you open a pull request, include:

  1. What you did — a short summary of the change.
  2. Why — what problem does it solve?
  3. Link to the todo.md item — if your change relates to one.
  4. How you tested it — what did you try to make sure it works?

Self-review checklist before submitting:

  • I tested the change manually and it works.
  • I checked for leftover debug prints.
  • My branch is up to date with master.
  • The code follows the project's style.

9. Testing

Right now testing is manual. Before opening a pull request:

  • Run python main.py and try your feature.
  • Try edge cases: empty input, wrong input, fast typing, whatever you can think of.
  • Make sure existing commands still work.

Automated tests may be added later. When they are, they must pass before merging.

10. Database notes

The project uses SQLite for now as database, read more about SQLite: click here to read more about SQLite.

  • The database file is products.db. It is already in .gitignore. Do not commit it.
  • To create a fresh database, run:
python database.py
  • If you ever need to start over, delete products.db and run that command again.

Clone this wiki locally