Getting started

This page explains how to set up Pynventory on your computer and walk through your first contribution.

Requirements

You need:

• Python 3.8 or newer
• Git
• access to the Pynventory repository
• a terminal or command prompt

If you are new to Python or Git, see the Useful links page.

Check your installed versions:

python --version
git --version

You should see installed version numbers for Python and Git.

If python does not work, try:

python3 --version

Clone the repository

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

Run the commands in this guide from the repository root.

Project structure

• pynventory/ - Python package with the app code
• data/ - local runtime data (gitignored except .gitkeep)
• tests/ - test package
• .github/ - issue templates, PR template, workflows
• README.md, requirements.txt, ruff.toml, .gitignore - project files

Create a virtual environment

python -m venv .venv

If python does not work, try:

python3 -m venv .venv

Activate the virtual environment

On Linux or macOS:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

If PowerShell blocks activation, run PowerShell as administrator and enter:

set-executionpolicy remotesigned

On Windows Command Prompt:

.venv\Scripts\activate.bat

When active, your terminal usually shows (.venv) near the prompt.

Install requirements

pip install -r requirements.txt

This installs Ruff for formatting and linting. The command should finish without errors.

Run the app

python -m pynventory.main

You should see the terminal app start and accept commands like help. Useful commands inside the app:

• help - show available commands
• add - add a product
• list - show all products
• mod - modify a product
• del - delete a product
• exit - close the app

Run Ruff

Before opening a pull request:

ruff check .
ruff format .

If ruff check . prints no issues or says all checks passed, the check is okay.

Only format files that are part of your change.

Database note

The app uses SQLite at data/products.db. This file contains local development data and must never be committed. If it appears in git status, leave it unstaged. See Troubleshooting for help.

---

Your first contribution

The goal is not to do something big. The goal is to make one small, clear change, open a pull request, and learn the workflow.

Pick a good first issue

Start with a small issue. Good first issues usually involve:

• documentation improvements
• small text fixes
• simple validation improvements
• small command-line output improvements
• simple cleanup tasks

Avoid starting with large changes such as:

• changing the database structure
• adding a web interface
• rewriting multiple files
• changing the full project architecture

If you are unsure whether an issue is a good first task, ask in the issue or on Discord.

Create a branch

Branches should normally be created from GitHub issues.

1. Open the issue you want to work on.
2. Find the Development section in the issue sidebar.
3. Click Create a branch.
4. Keep the default branch name unless there is a clear reason to change it.
5. Copy the commands GitHub shows.
6. Run those commands in your terminal.

This connects your branch to the issue and makes the work easier to track.

Make a small focused change

Keep your first contribution small. A good first pull request should:

• solve one issue
• change only the files needed for that issue
• avoid unrelated refactoring
• avoid formatting files you did not otherwise need to change
• be easy for another contributor to review

Test your change

Before opening a pull request, test your change manually.

At minimum:

• run the app with python -m pynventory.main from the repository root
• try the command or behavior you changed
• try at least one invalid input if your change affects user input
• confirm the app does not crash
• check git status before committing

After git status, only files related to your change should appear.

If data/products.db appears as modified, do not include it in your pull request. See Troubleshooting for help.

Need help?

If setup or testing fails, include the command you ran, the full error message, and what you expected to happen when asking for help. See Troubleshooting for common setup problems.

Open a pull request

When your change is ready:

1. Push your branch to GitHub.
2. Open a pull request into master.
3. Fill in the pull request template.
4. Link the issue using Closes #issue-number.
5. Explain how you tested your change.
6. Request a review.

Example issue link:

Closes #12

During review

Code review is part of the learning process. You may receive comments asking you to:

• explain a choice
• rename something
• simplify code
• test another case
• make a small correction

This is normal. Review comments are about improving the work, not criticizing the person.

After your pull request is merged

1. Switch back to master.
2. Pull the latest changes.
3. Delete your old branch.

git checkout master
git pull origin master

Remember

The best first contribution is small, clear, and finished. You do not need to understand the whole project before helping. Learning the workflow is already a valuable contribution.