Information for libreboot developers and contributors

Useful information, related to libreboot development, including links to the Git repositories where development is done. Development discussion is done on IRC and on the libreboot subreddit

Back to home page

How can I help the libreboot project? #howtohelp

At any given time, here is a list of tasks if there are any, for the next stable release of libreboot: click here - this is also where to send bug reports.

There are many ways that you can assist the libreboot project. We have a list of tasks that need to be completed, which you can work on (you can also add to that list). Generally speaking, adding support for more hardware is a priority for the libreboot project. Information about building libreboot can be found at here.

We especially need more skilled coreboot hackers to do work that will benefit the libreboot project. This includes porting new boards to coreboot, which are likely to be valid candidates for libreboot.

Learn libreboot from the inside out; download the git repository, and study libreboot. We need more full-time developers who can help to maintain the project.

Not a developer? You can still help!

General guidelines for submitting patches #guidelines

Some people put their name on their work, for recognition, and it's OK if you want to do that; however, the libreboot project does not require this. Some projects (such as coreboot) require a legal name, and this can be problematic for certain groups of people.

Using your legal name is not required when submitting patches to libreboot. For reasons why we have this policy, read this article. You can use any name of your choosing, or your company name (if you have one), if you want or need to do that. You can also submit patches without a name, if you want or need to do that (instructions are provided on this page). Also, read this article. Unfortunately, git appears to be stuck with these problems, when an author changes their name, and we don't have a concrete answer to it. As far as we know, publishing your legal name isn't even required for copyright purposes; in fact, "pen" names are commonly used by literary authors (computer programs are literary works).

When submitting any kind of documentation, try not to use the terms him/her, she/he, his/her, or anything that is gender biased. Use their, they, them, those people, that person, and so on. You are making a huge difference.

Generally speaking, using the same license as the file that you are modifying is much simpler. If you are submitting new files, please make sure that they are under a free license (copyleft preferred). You can find a list on: https://www.gnu.org/licenses/license-list.html (we will reject any documentation released under the GNU Free Documentation License, for reasons mentioned in ../why-not-gnu/). NOTE: not putting a copyright notice on a work does not mean it lacks copyright. Copyright is automatic in most countries. Not putting a license on a work also does not make that work free; you have to declare a free license, otherwise the default, restrictive copyright laws apply for those who wish to do anything with your work. Always put a license on your work!

Back to top of page

How to download from the Git repository #download

Libreboot development is facilitated by git, a distributed version control system. You will need to install git (most distributions package it in their repositories).

Coreboot distribution. This also contains the documentation:

Use this command, to download the repository:
git clone https://notabug.org/vimuser/libreboot.git
...you can also browse this repository on the web

A new directory named libreboot will have been created, containing libreboot.

Website. Documentation is in the other repository:

Use this command, to download the repository:
git clone https://notabug.org/vimuser/libreboot-website.git
...you can also browse this repository on the web

A new directory named libreboot-website will have been created, containing the libreboot website files.

Backup repositories

Use these if one of the main repositories are down.

Firmware (coreboot distribution)

Use this command, to download the repository:
git clone https://libreboot.org/repo/libreboot.git
...you can also browse this repository on the web

Libreboot website

Use this command, to download the repository:
git clone https://libreboot.org/repo/libreboot-website.git
...you can also browse this repository on the web

Back to top of page

How to submit your patches #sendpatch

Method 0: Use NotABug pull requests

NotABug, libreboot's main git hosting provider, now provides a pull requests feature. https://notabug.org/vimuser/ has the libreboot and libreboot-website repositories. Create an account on the website, then view the libreboot or libreboot-website repo and click "fork" and clone your fork. Then commit your patch on top, and push into your repository (we recommend into a non-master branch). NotABug guides you through the process of pushing patches to it.

Once you have pushed your patches, go to the relevant repository on https://notabug.org/vimuser/ and click "Pull Requests". Then click "New Pull Request". Select the relevant branches that you want to submit a pull request for, between the two repositories, and then click "Submit".

When this is done, Leah Rowe (maintainer of the main repository) or someone else (with push access) will review your patch, and decide whether to merge it. Relevant links to bug trackers for discussing development (especially patch review) are on ../tasks/

Method 1: host a repository

Give the checkout details to Leah Rowe, along with information on which commits in what branch contain your changes.

Check #githosting, for a list of Git hosting providers that we recommend.

Method 2: git format-patch -N

Use this method (replace N with the number of commits that you made) and send the .patch files to the libreboot project, along with details on what branch and revision these were made on top of.

Give the checkout details to Leah Rowe, along with information on which commits in what branch contain your changes.

Back to top of page

List of recommended Git hosting providers #githosting

There are several that we could recommend:

The libreboot project itself uses all of the above options.

Most Git hosting providers distribute non-free JavaScript on their website, but as far as we are aware all of these providers are freedom-friendly and reliable to use (and their JavaScript is free). This list will be expanded upon at a later date. The hosting providers above are all powered by Free Software, which means that you can also host your own version of the software that they use on their website.

We generally recommend self-hosting (first option in the list above). Git is a decentralized (distributed) version control system. However, not everyone can afford to do this, so using one of the other providers on the list above is also acceptable.

**PLEASE** DO NOT USE GitHub. Learn more here.

**PLEASE** DO NOT USE GitLab. Learn more here.

Back to top of page

How to use git, for creating patches #contrib

Libreboot development is facilitated by git, a distributed version control system that is in wide use today. Git provides many practical benefits, making collective development of software very easy.

The git documentation describes how to use git. The following notes include simple tips for how to use git, but it is a good idea to get fully acquainted with git.

Make sure that you configured git so that your name and email address appear in the commits that you create:
git config --global user.name "Your Name"
git config --global user.email your@emailaddress.com
NOTE: you do not have to use your legal name; we don't care what name you use. You can use any name of your choosing. If you wish to be anonymous (no name), you can also use Libreboot Contributor as your name, and noname@libreboot.org as the email address. We will happily accept anonymous contributions in the libreboot project.

The following is also useful:
git config --global core.editor vim # NOTE: on most systems, git defaults to using vi anyway. If you switch to vim, make sure it's installed
git config --global color.status auto
git config --global color.branch auto
git config --global color.interactive auto
git config --global color.diff auto

NOTE: the above steps for colour make git use red/green font colours for showing diffs. If you are red/green colour-blind, please ignore the above steps. The default configuration in git is no-colour (all one colour, usually the default that your terminal uses). If you are colour-blind, git can display in other colours; refer to the git documentation.

Clone the git repository, and make your desired changes inside the newly created libreboot directory. You can make one or several commits (as many as you like). Generally speaking, you should create separate commits on top of each other, for each kind of change.

When working with git, you will need your current working directory to be inside the libreboot directory that was just created.
cd libreboot/

Once you have made your change(s), you can use this to check the status:
git status

The status command will show any untracked files that you have. Add them using git add path/to/file. You should also add any other files that are listed as modified in the git status. If there are deleted files in the git status, you can use git rm path/to/file. As long as you have added all the untracked files, it is generally easier to use:
git commit -a
(instead of git commit)

If you need to make a change to the current commit, you can do so with:
git commit --amend
or:
git commit -a --amend

If you wish to use a different author name for the commit command, add --author="Author's Name <author's email address>" at the end. This could be any name your choosing, or it could be because you are submitting a patch on someone else's behalf. If you wish to be anonymous (no name), you can also use Libreboot Contributor as your name, and noname@libreboot.org as the email address. We will happily accept anonymous contributions in the libreboot project.

Check once more that everything you want is added. Use the git status command to check for untracked changes/files, and adapt accordingly. Once you've committed everything, your changes will appear in a diff format, using this command:
git show
Use PgUp/PgDown to navigate the diff output. This uses the less utility, so all the features from that (e.g. keyword search) are also available.

In your local git tree, you can use this to check your commits:
git log

Shortened git logs showing the short commit ID and the commit title, plus info about what branch you are on, and where all your remotes/heads are:
git config --global --add alias.lol "log --graph --decorate --pretty=oneline --abbrev-commit --all"
From then on, you can use:
git lol
This is like git log, but it's much better and shows branches, etc.

Back to top of page

The source code for this page is available from a git repository.