Project:PkgCore

PkgCore
Description	The PkgCore Project is devoted to maintaining and updating the pkgcore stack, the other package manager for Gentoo and its ebuild format, and the tools based on it, which includes pkgcheck and pkgdev.
Project email	pkgcore@gentoo.org
Packages	p.g.o/pkgcore@gentoo.org
IRC channel	#pkgcore (webchat)
Bugs	Related bugs
Lead(s)	Arthur Zamarin (arthurzam) No lead election date set
Member(s)
Subproject(s) (and inherited member(s))	(none)
Parent Project	Gentoo
Project listing

The PkgCore Project combines efforts of multiple developers to add new features, fix bugs and improve user and developer experience with the PkgCore stack, which includes mainstream tools such as pkgcheck and pkgdev.

Contributing to PkgCore

The PkgCore is written in Python, and has fully separate code base from Portage. It is divided into multiple different repositories. Contributions are very welcomed, and in case questions arise, feel free to ask for help in the various communication channels.

The repositories are hosted on multiple platforms, with the once at Gentoo's gitweb being the main one, and the once at GitHub and Gentoo's GitLab being mirrors, and the main interaction point with the development. Please note that the repositories at Gentoo's gitweb are subject to strict access controls, and pushing tags to this repository is restricted to the project lead.

For most contributors we recommend to use GitHub or Gentoo's GitLab, as it is more user friendly on both ends. Feel free to open pull requests or issues.

The repositories are:

1. snakeoil - Gentoo's gitweb, GitHub, Gentoo's GitLab
2. pkgcore - Gentoo's gitweb, GitHub, Gentoo's GitLab
3. pkgcheck - Gentoo's gitweb, GitHub, Gentoo's GitLab
4. pkgdev - Gentoo's gitweb, GitHub, Gentoo's GitLab

Also please note that a Sign-Off to Gentoo's GLEP-76 by the contributor is required. When the change is approved, a project member will merge the contribution, while also GPG signing the commit. Note that the push should be done to the Gentoo's gitweb repository.

To thank our contributors, any contribution is listed and the contributor is mentioned in the release notes. You can of course request to not be listed in the notes, which is acceptable, but we like to thank the contributors and put their name on the Wall of Fame.

Creating developing environment

While possible, we don't recommend to develop without a virtual environment. The recommended way to develop is to use a single virtual environment into which you install in editable mode the full stack.

1. Create a main directory which will contain all the repos, let's call it /pkgcore
2. git clone all 4 repositories into this directory
3. Create new virtual environment: python -m venv venv (this will create a directory called venv, which you should activate by using source venv/bin/activate)
4. Install in editable mode the 4 packages, in this precise order:
   1. pip install -e "./snakeoil[test,doc]"
   2. pip install -e "./pkgcore[test,doc]"
   3. pip install -e "./pkgcheck[test,doc]"
   4. pip install -e "./pkgdev[test,doc]"
5. Now, you work on the whole stack level, change in one part and view how it affects other parts. If you are using smart IDE, you can even debug across the stack and more.
6. Before committing , please run black formater using make format to format the code.

Joining the project

Any Gentoo developer can join the project, by contacting the project lead. We expect help in any place possible, commits, reviews, proofreading, documenting, etc. This can be done on GitHub or GitLab repositories. Stricter control is done on write access to gitweb repository, as this is considered the source repository for live ebuilds of the stack, which are used by a lot of developers (official and unofficial). Only the project lead should have permissions to push tags to gitweb.

Reporting bugs

Every software has issues and bugs, and PkgCore stack isn't an exception to this rule. While we hope we can test any flow, and we try to always improve our test suite, we can always miss some new flow.

Which is why a special component was created for this stack, to make it easier to report new bugs and for us to search them.

While for some Bugzilla might be more comfortable, you can also report bugs in the corresponding GitHub or Gentoo's GitLab repositories. This way you will have better watch on the development process to fix your report.

Note
Please note that sometimes additional info will be requested by a project developer, to try to reproduce the bug. Please cooperate with the requests as possible.

Bug with pkgcheck commits scan

When commits scan is performed by pkgcheck (during pkgcheck scan --commits or pkgdev push), occurring bugs are very hard to reproduce. To enable PkgCore developers to reproduce the bug and debug it to create a fix, we need to get an exact git state. When opening a bug, please add those 2 points:

1. Commit id of origin/master - pkgcheck is using this commit as base of the commit range.
2. Link to a branch containing your master state exactly as during the bug state. Don't rebase over latest tree state, push the state exactly as during the failure.

With those 2 points of information, we can change the ref of origin/master on our local repository, git reset --hard to linked branch, and most of the time reproduce the bug. While most of the times it should reproduce, it might be some race, so appending other reproducers is welcomed. When a developer replies "reproduced" to the bug, there is no need to add more reproducers.

Requesting features

PkgCore Project accepts happily feature requests of various types, listed below. We all want the tools to be better, for simplifying the usage and development efforts for Gentoo. We want your feature requests!

Similarly to reporting bugs, we encourage you to request features in the special component in bugzilla, or in the corresponding GitHub or Gentoo's GitLab repositories. Currently the preferred channel is GitHub repositories.

Also note that the development time of PkgCore developers is finite, so some requests might get higher priority, or just randomly selected by a member to implement. If the request is still without progress, we encourage you to try and develop yourself.

New QA check

While pkgcheck has a lot of checks, we want to bolster the amount so we can improve the quality of ebuilds in Gentoo. But for new checks, to have easier development, we request you include the following information:

• Example ebuild and line number with "bad" code. Preferably add a link to an ebuild in overlay (or main Gentoo tree) with specific commit id (in case the ebuild changes, we can find the original version). By using an example we can have easier time to test the new check, and understanding the desired behavior.
• A diff that should fix the ebuild. Having such a "fix.diff" makes it much easier to develop.
• The message to output.
• The expect result level, one of error/warning/style/info. While it might change after further considerations, an initial level is nice to have.

Higher priority is given to request from Project:Quality Assurance, as in some way pkgcheck tries to minimize future work needed by QA team. Also note that some new checks requests will ask for approval by QA team, to minimize future conflicts with other Gentoo developer.