Your first contribution

This page walks you through making your first contribution to Pynventory.

Before starting, make sure you have the project set up locally. See Getting started if you have not done that yet.

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.

For a full testing checklist, see the Testing guide.

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. See the Code review page for details on how reviews work.

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.