User:Maffblaster/Drafts/Gentoo Primers/The Gentoo Developer Primer

This document should not be considered a replacement for the old Developer Handbook. Eventually this article may get merged into the Developer Handbook. Right now it is simply to be used as a draft space of steps necessary for developers to become connected and productive in the Gentoo sphere. New developers should travel down through the list.

Developer initiation
New developers have quite a few things to setup before they're 'fully integrated' into the Gentoo ecosystem. For developers that are unfamiliar with processes and job duties of system administration (perhaps more code-savvy and less infrastructure oriented developers), configuring these things can be a confusing and difficult. Because of the sheer amount of tasks, it's also easy to

SSH key
SSH keys will need to be generated so that woodpecker, and potentially Gentoo development machine, can be accessed. The recruiter(s) will assist in this process, but essentially generate a 4096-bit RSA key pair:

Be sure to enter a strong passphrase. Do not leave the passphase blank!

After generation, the keys will be located in directory. The public key (typically found at ) will be added to Woodpecker for you by your recruiter. The private key (found at ) should never leave the machine and should only be readable by your user:

See the SSH article for more information.

Configuration file
Developers working with multiple SSH keys can setup an SSH configuration file in order to conveniently associate specific SSH keys with specific remote hosts. For example, a developer named Larry - our favorite cow - has three separate SSH keys: one for personal use, one for work, and one for Gentoo work. He can make SSH aware of such a setup by creating a file in  directory:

Many more configuration options are possible. Investigate in.

GPG key
To reference at any point during the following sections on :


 * GPG Cheatsheet
 * GPG Cheatsheet
 * GPG Cheatsheet

Create a backup
Those without existing GPG keys should skip this section. Creating a backup is best practice for those who have existing GPG keys from other projects:

If anything in the following steps goes foul the backup is now located at.

Master keys
It is best practice for developers to generate a master key pair, then generate subkeys from the master key pair for signing. Generated keys are to follow the specifications outlined in GLEP 63. In short, Gentoo developers are to use a master key type of RSA at 4096 bits (RSAv4 or later). Developers who have already generated a master key that does not meet this minimum standard will need to generate a new set of keys (sorry!).

The Infrastructure project has some documentation on how to generate keys compliant with GLEP 63.

After emerging, issue the following commands:

Copy and paste the following GLEP 63 approved configuration template into :

Generate the master key pair by running the following command, then entering the values found in the numbered section below:

At the dialog:


 * 1) Choose the "" option (should be the default).
 * 2) For key length, be sure to enter.
 * 3) Enter the GLEP 63 recommended value of   for the key expiration.
 * 4) Enter a name, the email address, and a comment (if desired) to be associated with this key. The comment is simply for your reference. Those with multiple master keys may enter a descriptor describing the purpose of this key in this field.
 * 5) Visually inspect the data is correct, then confirm the entries by pressing the  key (O as in Oscar) and.
 * 6) Enter a strong passphrase (be sure include at least one integer number in the passphrase or GPG will provide a warning).

GPG should now be generating a master key pair! This will take some time and will benefit from system resource usage. Updating some software, playing a game, or reviewing bugs is a nice way to pass the time. When finished, the keys will be present in the directory!

Subkeys
According to GLEP 63 signing subkeys are optional. If the developer would like to use subkeys instead of the master key pair for signing, this section will provide instructions on how to do so. GLEP 63 recommends a 1 year maximum expiration on subkeys with a renewal every 6 months.

Get the master key's ID:

In this example  is master key's ID; this is what is needed in the next command:

This will make enter into an interactive mode:


 * 1) Select "" (typically  ).
 * 2) On the next prompt be sure to enter a value of   for the bit size.
 * 3) Set the expiration to a value of   and confirm.
 * 4) Enter the passphrase of the master key.

After some time the signing subkey will be generated.

In order to set this subkey to be the default for signing the configuration file will need to be adjusted. Use the  option with the key IDs in long format again to determine the newly generated subkey's ID:

The subkey should be displayed at the bottom of the list. The subkey ID in this example is.

Open the file and uncomment the line referencing :

Remember, this subkey will be expired in one year from the generation date. When it is expired a generate a new subkey by following the steps above. Be sure to update each location the subkey should be referenced (namely, , and ).

Sending keys
Once all keys have been created, it is necessary to send them to key server pools:

Developers must also submit it to Gentoo's independent pool:

Pinentry
pinentry should be configured based on developer preference. There are a few visual interfaces to : Qt, GTK, and ncurses. Adjust the USE flags for the program as necessary. If the KDE or GNOME desktop environments are being used, it is likely either the  (or perhaps  ) or the   USE flags have respectively been set.

After adjusting USE flags and recompiling as necessary, be sure to use to select the appropriate user interface. In the example below the Qt 5 interface has been selected:

Next configure file to prompt for a password via :

dev.gentoo.org
dev.gentoo.org (sometimes shortened to d.g.o, woodpecker, or just pecker) is primarily used to setup a developer's LDAP information and add developer email addresses to email aliases and project groups. However it can also be used to notify the community when taking a leave from developer duties via a file and as a space to host Gentoo related files or a development website or blog. These changes are performed using the script.

Each change will require the developer's password to be entered. Developers that may not remember their password can test their passwords here.

LDAP
Lightweight directory access protocol is used by Gentoo's infrastructure team in order to maintain an internal database of information about Gentoo developers. The next section rehashes the basics of setting developer information in LDAP. See Infrastructure's LDAP Guide for the latest updates.

If a user named Larry were to add himself to some roles for Gentoo, he would execute the following command:

Although roles are flexible in name, they roles should match your project affiliations as defined by your actual project involvement. Ideally involvement will line up with the Developer infobox here on the wiki.

To set longitude and latitude information (find it on a per-city basis here):

Setting longitude and latitude in LDAP will enable a location marker which will display a pin for your user on the developer map.

GPG key
expects the GPG signing key to be passed in fingerprint format. The following command will show the fingerprint format for subkeys (having  twice is not a mistake):

In the above example  is the signing key in the fingerprint format.

Absence from developer duties (AKA devaway)
As life demands time away from Gentoo developer duties, developers have a method to provide notification to others in the community of their absence. This is performed via an (AKA devaway) file in the root of the developer's home directory.

The away message and auto-generated time stamp will be displayed two places:


 * 1) https://www.gentoo.org/inside-gentoo/developers/unavailable-developers.html
 * 2) https://dev.gentoo.org/devaway/

Information on creating a developer away file can be found in this Infra project article.

Developer web space (AKA devspace)
dev.gentoo.org can also be used to host developer related files and/or a website, blog, etc. HTML, SHTML, and PHP support is available.

See this Infra project article for more information on web services (aka devspace).

Bugzilla
bugs.gentoo.org (often shortened to bugs.g.o, or b.g.o), Gentoo's Bugzilla site, is where all bug information should coalesce. As with any healthy, audible project: if bug information does not end up in Bugzilla, then future audits are difficult to perform.

Bugzilla currently uses a separate password than dev.g.o, so be sure to record the password in a safe location.

See the following projects for more information:


 * Project:Bug-cleaners
 * Project:Bug-wranglers

Wiki
Visit the Developer Central page and click the Link your developer account button in order to connect your LDAP information to the wiki.

GitHub
Until a better, self-hosted system can be implemented, Gentoo is using GitHub to accept community contributions. Gentoo developers should create a GitHub account and add the following:


 * Add your public GPG key to your GitHub profile.
 * Add your public SSH key to your GitHub profile.
 * Developer can alternatively use SSH forwarding instead of adding their public key to GitHub's server (requires more time/effort).
 * Two-factor authentication (optional, but recommended for developers with a phone).
 * Personal access tokens (if two-factor authentication is enabled). Enable the following scopes for Gentoo related access tokens:
 * repo
 * admin:org
 * read:public_key
 * admin:repo_hook
 * gist
 * read:user
 * user:email
 * delete_repo
 * read:gpg_key
 * Add the Gentoo development token to the file.
 * Use SSH URLs (alternative to access tokens).

make.conf
All Gentoo developers should have GPG (PGP) and SSH keys (generated in the Keys section above). Git needs to interface with both keys. This is done in order to verify and validate identity.

In this example  is the part that would be added a value to the PORTAGE_GPG_KEY variable inside, as well as our SIGNED_OFF_BY :

Configuration file
The options can be added via by running the following commands:

When the above commands have been entered, the developer's git configuration file should look something like the following:

As of v2.31, git can be configured to prefetch objects from upstream remotes using. Using this feature, Gentoo developers can streamline their development efforts. See the upstream documentation for the new subcommand and configuration file details.

IRC
Most developers stay connected 24/7 to Libera IRC in order to catch any mentions of their nickname by other IRC users. There are various strategies of staying connected. Some developers leave their main or secondary workstation (home or cloud server - when running at home a low power device such as a Raspberry Pi works well) connected to the internet, some developers leave a or  session running an IRC client ( and  are available) running on dev.gentoo.org (woodpecker) and SSH, others might pay for a cloud-based IRC service such as IRC Cloud. In IRC jargon, the term for a software system that stays connected on behalf of an IRC user is called a bouncer.

For those wishing to host an IRC bouncer themselves, the IRC guide is a great place to start.

Creating new channels
On occasion it may be necessary to create a new channel on Libera IRC for new projects. This is a multi-step process, but any developer can claim (the proper IRC term is "found") a #gentoo- channel by registering it, then running the appropriate commands for channel configuration. For example, using, and setting the new channel name to "gentoo-new-channel" and the founder's as a developer named "larry":


 * 1) Join the channel to be registered:
 * 2) * At this point the channel should be empty. If there are other users lurking, then the channel name is likely already chosen. Try again with a new channel name if this is the case.
 * 3) Open a new chat window / buffer with ChanServ:
 * 4) * Register the channel:
 * 5) * Set the channel email:
 * 6) * Set the channel entry message:
 * 7) * Set the channel topic:
 * 8) * Set the channel url:
 * 9) * Set the founder to automatic op:
 * 10) * Set all cloaked Gentoo developer accounts with automatic voice:

Projects
GLEP 39 specifies the procedure for starting (and joining) a project, but in summary:
 * 1) Ask the project lead first about joining the project.
 * 2) Every project has a wiki page. Joining is done via ediiting the page:
 * 3) Press 'Edit Form'
 * 4) Add the new user as a member
 * 5) Save!
 * 6) Edit the relevant alias in  on dev.gentoo.org if one exists.
 * 7) Join the relevant project IRC channel if one exists.

Mailing lists
It is possible to add one's self to various project mailing lists by visiting dev.gentoo.org, navigating to the or  directories, and locate the appropriate project's mail alias handle. These files can be edited using a standard text editor such as or.

Forums

 * Create a forums account (optional).
 * Join #gentoo-forums on IRC and request that your account be given developer status.

Blogs
Many Gentoo developers have blogs. This section will present a few options for Gentoo developers.

The first option is creating a Developer website on Woodpecker, which can be used to host any kind of file. Simply make it a website by adding an file.

The second option for Gentoo developer is to use the Wordpress site, via https://blogs.gentoo.org.

If none of these options work, you can always host the blog somewhere else. As long as it has an tag-generated RSS feed, the Gentoo Planet blog aggregation site can pull in the Gentoo related postings.

Atom/RSS feeds
Subscribing to Atom/RSS feeds is a great way to stay connected and get the latest news concerning a project or bugs in Gentoo. The FireFox web browser previously included such a feed reader built-in to the browser. It is still possible to receive feeds via web browser, however plugins / addons are now necessary to extend functionality.

Alternatively, single purpose applications such as, make for a great substitute for functionality built-in to a web browser.

Bugzilla
The main page of Bugzilla offers a method to users with accounts to subscribe to "Open bugs assigned to me", "Open bugs reported by me", and "Requests addressed to me".

Security

 * RSS - https://security.gentoo.org/glsa/feed.rss
 * Atom - https://security.gentoo.org/glsa/feed.atom

Portage configuration
Package maintainers will need to provide Portage with their GPG signing (denoted by the ) key information in 0xlong format. This is a different format than expects on Woodpecker. Use the following command to display keys in the proper format:

In this example the  signing subkey is the part that would be added a value to the PORTAGE_GPG_KEY variable inside :

By default Portage does one thing at a time. Adding the following values to Portage's FEATURES variable will speed up the development process. Each feature explained in the file box below:

There are additional options which should be set to find QA issues. At minimum:

It is suggested to try too.

Repoman
is a quality control utility for ebuild repositories. It is generally used by Gentoo developers for repository linting and formulation of consistent commit messages.

User configuration
Be sure to add the account(s) used for developerment to the Portage group:

This will let the developer modify files owned by Portage.

Testing environments
TODO add links here to various developer test harnesses. There is no one size fits all...

Tooling
When attempting to preform fine work, having sharp, precise tools is a must. This section of the developer primer will hopefully provide aid in helping developers streamline their workflow. The goal is an increase in productivity.

bash
Since the EAPI and bits of Portage (the development command) are built on, using it should become second nature for the Gentoo developer. Other shells can be fine for personal use on the command line, but for development purposes it is necessary to have a solid understanding of bash.

In addition to the devmanual's bash page, the bash hacker's wiki contains useful information. Many ebuilds and eclasses use parameter expansion, string replacements, and other 'advanced' features. Be sure to review as necessary to gather knowledge.

is a very useful static analysis tool, a must-have when checking scripts for correct syntax and safe operation:

Email clients
Depending on the selected email client, getting setting configured properly to filter incoming messages into nicely organized directories and remove nasty spam can take some time and effort. It is important that every developer take the time to properly configure the email client of choice for developer related duties for a few reasons. A well thought out configuration at the beginning will:


 * Save time.
 * For most every developer, checking mail is only one of the streams of communication that will need checked on a regular basis. The less time spent checking mail the more time can be invested into checking other communication streams such as IRC, comments on GitHub, or other Gentoo project sites. Ideally Gentoo developers will be spending the majority of their time on coding, ebuild maintenance, hacking on infrastructure, or other Developer/SysOp duties.


 * Gain efficiency.
 * An efficient person is a productive person. Having the mail client sort and prioritize messages offloads cycles to a CPU rather than a human brain, which allows the human brain to concentrate on what is important.

aerc
is a lightweight mail client written in Go. Setup includes a nice startup wizard to assist users in connecting to their first mail server.

In general, to setup, run, enter the values as appropriate, substituting as necessary. It should take all of about 2 minutes to get connected.

Basic account information:

Incoming mail (IMAP):

Outgoing mail (SMTP):

Once the program is connected to a mail account, it is helpful to perform some configuration changes to make it more friendly for reading Gentoo related mail.

To view embedded text/html MIME types, the and  packages should be installed (according to ), and the text/html filter uncommented in the  configuration file. If conversation threads are desired, then (for at least v0.7.1 and prior) a filter will need to be applied to enable threading:

Thunderbird
Useful link for spam filtering:


 * https://support.mozilla.org/en-US/kb/thunderbird-and-junk-spam-messages

Remember that Mozilla's spam filter needs training, so it may take some time (a week or two) for it to learn what is spam what is not. Be sure to check whatever folder is dedicated to Junk every once in a while to be sure important messages are not being incorrectly marked as junk!

mutt and neomutt
Both and  are available in Gentoo.

notmuch
is not a mail client, but it is a powerful and efficient message filtering and search tool for use with text mode/commandline mail clients. notmuch integrates with mutt, neomutt, and aerc.

External resources

 * https://devmanual.gentoo.org/ - Gentoo's official developer manual.