Development Guide

Overview

Okay, so you want to get involved. How do you do it?

First, it is important you understand the Funtoo way.

The BDFL

Funtoo Linux follows a BDFL model. Think Linux kernel. There is a benevolent dictator for life (me, Daniel Robbins) that oversees all things. Note that this is not the same as doing all things nor does it mean deciding all things. We are a user-focused distribution so your needs are important.

The jobs of a BDFL are many.

One job I have is to define a process for development for Funtoo. This process involves sending pull requests via https://code.funtoo.org. It is important to understand this process, and also understand how https://bugs.funtoo.org is a part of it. As BDFL I am always telling people to file a bug. I repeat it over and over again. I sometimes see people saying "that Daniel really loves his bugs." Well, there is a reason why I love bugs, or at least bug reports.

The Importance of Bug Reports... and Bad Kung-Fu

From the perspective of making Funtoo better, the following statements are true:

If you are experiencing an ongoing problem with Funtoo and have not reported a bug, you have not done enough communicate your problem.

Yes, that is even true if you have talked about it on forums or on Discord. Bug reports are important.

I love bug reports because the goal of Funtoo is to create and maintain reliable software, even perfect software (why not?) If you have come from Gentoo, you may be used to figuring out what USE variables to set by hand, and then dealing with any problems from your choices, and getting your system working. Along the way, maybe you encountered some weird issues but found ways around them either by your own troubleshooting or on resources like forums or similar. Maybe you filed a bug with Gentoo but it was not fixed in a reasonable time frame so you just learned to fix your own problems. I am not saying any of this to disparage Gentoo -- it is just that I believe this is a common experience and we have people coming from Gentoo all the time who tend to have these habits and perspectives. You are a Gentoo frontiersman, and have learned to fend for yourself.

This "deal with the problems on your own" approach can be rewarding, and you can learn things from it, but I will argue that if you come from this way of doing things that you may have learned some bad Kung-Fu. In Funtoo, you are part of a community. You are expected to "join in" with this community, and our core way of joining in is by filing bug reports. In Funtoo, if you leave out this part, then you are not fully participating.

I'll explain this in more detail below.

Funtoo Should Work. Because We All Benefit.

I want Funtoo to work, because I use it. I want it to work for everyone. If it doesn't work for you, a bug report lets Funtoo "see" that there is a problem. Due to the community nature of Funtoo, we rely on your eyes to tell us what isn't working, so we can fix it. We want it to work for you, and for us. We also understand "the law of the jungle" -- that if it works better for you, it will work better for us, too. Your eyes and voice are important for the community to work.

We also rely on your requests to know what packages to add, so we can add them -- though we really like to have a clear explanation for why the package you want is important to you. Your story is important. Funtoo is a community of people, and we maintain a technology that works for us. We are motivated by the needs of our users, and when we fully and deeply understand your need on a personal level, not just your "ask", we take it seriously and try to support you if possible.

Help Me To Help You

So when you don't report a bug, you are not letting others help you. And really, it hurts others, because eventually we will run into this bug too, and we will be frustrated by it, because we want software to just work, too. The earlier a bug is reported, the sooner it will be fixed, and the fewer people will be frustrated by it. So that's why it's so very important to file bugs. When you file a bug at https://bugs.funtoo.org, you are truly participating in the Funtoo community and helping the community to have visibility of these issues so they can be fixed quickly.

Maybe you came from a project where developers really hated getting duplicate bug reports. I love duplicate bug reports. File all the duplicate bugs you want. I will gladly deal with duplicate bugs if it helps us make sure that we have all bugs reported. Dealing with duplicate bug reports is a piece of cake, but trying to fix a problem you don't even know exists is impossible.

So if you have a problem, make sure there is a bug for it. If you don't see a bug for your problem, create a new bug.

Funtoo Philosophy on Bugs

The Funtoo philosophy on bugs is very simple:

All problems should be reported to the bug tracker, so we can see problems.
If it is broken, it should be fixed correctly, so we can make software more perfect. "Fixed correctly" means "something just works normally and intuitively without requiring any special manual workarounds by the user."
If fixing the problem this way isn't feasible, we should find an acceptable and elegant workaround, so the software is usable, and things work normally and intuitively without any special steps, even if the technical part of the fix we use to get things working elegantly may be a short-term or less-than-optimal fix from a technical perspective.
If neither of these options are possible, a manual workaround can and should be used. This allows the software to still technically work. These workaround steps need to be communicated to users so they are aware of them, to prevent frustration of trying to figure out these steps themselves. We have at least allowed our users to have a path forward -- with some bumps -- until we can fix the problem better.
Our documentation and software should be simple, so we continually try to reduce or eliminate any required manual workarounds, and replace them with "better" fixes so that things will "just work" -- as soon as we can.

When you click "Create" on bugs.funtoo.org, you will see further instructions in green on how to file an ideal bug report. These instructions will help you to focus on what's important -- telling your 'story', or experience, so that the Funtoo community can understand your perspective.

Bug-Tracker Centered Development

With all of the above in mind, it should now be clear why the bug tracker at https://bugs.funtoo.org is central to our work.

To use the bug tracker, log in using your Funtoo account you created at https://auth.funtoo.org, and specify your username in lowercase.

File a bug. It will be in the "Intake" state. When it is ready to be worked on, it will be moved to the "Ready to Fix" state. When it is in "Ready to Fix" state, then pull requests (PR) can be submitted via https://code.funtoo.org.

When you file a bug, have confidence that we want the software to work for you, and will try our best to support you. And have confidence that you are fully participating in the Funtoo community.

The Nitty Gritty

First, make sure you have the current release of Funtoo Linux installed on at least one system.
Find things that need fixing on the bug tracker, and submit fixes for them (see video below on how.)
If you have a new ebuild, submit a pull request to kit-fixups (see YouTube videos for details.)
Testing things and finding bugs is also a form of help.
Help us document stuff on the wiki. See How to 'wiki'.
Hang out in Funtoo Discord or Funtoo Telegram Channel and chat with us.
Learn more about ebuilds by perusing the documentation below. Ask questions. Try out Metro.
Announcements are posted to the News and Announcements section of Funtoo Forums.
To track other updates, such as wiki updates, subscribe to funtoo's RSS and Atom feeds.

Getting Started

To get started with Funtoo development, it's strongly recommended that you first watch the following video, which will introduce you to code.funtoo.org and explain how to use it to fork a repository and create a pull request. Forking a repository and creating a pull request is the best way to start doing Funtoo development:

Here is a follow-up Development_Guide/ebuilding video with close to an hour of tutorial-style instruction:

Funtoo Distinctives

To get familiar with Funtoo Linux internals, such as kit-fixups, and how they work, please be sure to read the following pages:

Ebuild Writing

To learn more about ebuilds and how to write them, the following pages are available:

Portage Variables -- learn about all those variables inside an ebuild, and in make.conf.
Ebuild Functions -- src_unpack, src_compile -- these are ebuild functions. There are others. See all of them and learn how they work.
Ebuild for package without sources -- how to make a package with no sources.

For a more comprehensive reference of all the details of ebuild development, please see the Gentoo Development Manual.

Advanced Topics

Creating Your Own Overlay

If you are maintaining several ebuilds for Funtoo, you may find it more convenient to maintain your own overlay and have us pull new versions of ebuilds from you, rather than having to create a pull request.

Creating Your Own Meta-Repo and Kits

Even more advanced users may want to use our own tree update scripts to generate their own customized meta-repo and kits. This document also covers the functionality of our tree update scripts in detail, and will give you some insight into how to work with the kit-fixups repository effectively.

Metro

To learn how to build your own Funtoo stages, please look at documentation for Metro.

Pages that need updating

Warning

These pages are stale and need updating!

Forking An Ebuild -- explains how to take an ebuild from Gentoo and fork it, so you can make local changes.
Portage (Funtoo) -- learn about Funtoo changes to Portage (needs updating).
Portage Dynamic Slot - dynamic SLOT functionality now in Portage.