Contributing

We welcome merge requests and issues being filed in our code repositories. Typically, issues get filed under the project that the issue relates to and you can browse our list of projects. For example, if you find an issue with the documentation, you can file an issue under the developer docs project. An issue can be any mistake you found in the project, e.g. a crash, a bug, or even a typo. You are welcome to file an issue when you want to make us aware of some important topic relating to the project as well.

Aside from project specific issues, we do have an Apps_issues project to track tasks like applications to port to the phone or issues with them. Here you can add a task for a particular app to be ported to the phone. However, be sure to search our list of projects first before opening an issue under Apps_issues.

Working on issues

Issues have an Assignee field, which is used for indicating that someone is working on it. Other people can avoid doing the same work if it’s already being taken care of. Anyone interested can assign themselves, even the person who filed the issue.

If you are filing an issue, and you know someone else can solve it better than you can, please use the @mention to bring their attention. Don’t assign other people yourself! Let them take a look before taking the responsibility.

If you wish to take up an issue yourself, you will need additional permissions in our GitLab so please reach out in the community/librem-5 Matrix room and ask for a team member to grant you the “Reporter” role for the relevant project.

Repository Guidelines

If you have a repository that you maintain but expect others to contribute to, then it is helpful for newcomers to know who to contact when they have questions regarding that repository. For this reason, we would like every repository to contain a doap file with the maintaner field filled out. Optionally, if you know of someone that will regularly review your merge requests, then the helper field should also be completed. For a list of supported doap fields, see this list on Wikipedia but below is complete example you can modify to match your project:

<?xml version="1.0" encoding="UTF-8"?>
<Project xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
         xmlns:foaf="http://xmlns.com/foaf/0.1/"
         xmlns:gnome="http://api.gnome.org/doap-extensions#"
         xmlns="http://usefulinc.com/ns/doap#">

  <name>YOUR PROJECT</name>
  <shortname>YOUR PROJECT</shortname>
  <shortdesc>DESCRIPTION OF YOUR PROJECT</shortdesc>
  <homepage rdf:resource="LINK TO CODE" />
  <license rdf:resource="http://usefulinc.com/doap/licenses/gpl" />

  <programming-language>LANG</programming-language>

  <maintainer>
    <foaf:Person>
      <foaf:name>MAINTAINER'S NAME</foaf:name>
      <foaf:mbox rdf:resource="mailto:MAINTAINER'S EMAIL" />
    </foaf:Person>
  </maintainer>

  <helper>
    <foaf:Person>
       <foaf:name>FREQUENT REVIEWER NAME</foaf:name>
       <foaf:mbox rdf:resource="mailto:FREQUENT REVIEWER EMAIL" />
     </foaf:Person>
  </helper>
</Project>

Be sure to adapt the above template to match your project info.

Submitting Patches

This section describes the workflow for submitting patches followed by the Librem 5 team.

The “production” repository will be in the https://source.puri.sm/Librem5/ space. A user that wishes to patch the code and make a merge request should do the following before submitting a merge request:

• Fork the desired repository into your own space and clone your new fork.
• Make a feature branch that is a pristine copy of the master branch.
• Make the code changes on this feature branch and test.
• When you are ready for the changes to be merged back into the production repository, make a merge request from your feature branch to the original project’s master branch.

Making Merge Requests

Merge requests (MRs) are meant for code which you would like to get merged. There are two possible types of those:

• Work In Progress requests have the “WIP: ” prefix in the title and are meant to gather feedback on the idea. These MRs can have failing pipelines, don’t need to be tested, and will not be merged. The following guidelines don’t apply to them. However, the author may remove the “WIP: ” prefix, making it a regular merge request.
• Regular merge requests are a way for the author to take a commitment to work on the code. In exchange, the project maintainers will provide feedback and include the change when they think it’s appropriate.

By making a merge request you are letting others know that your change has been tested and you feel it is ready to be live. Since MRs should be reviewed by another person and in order to minimize misspent effort, we have come up with a short set of guidelines around merge requests.

• In each commit add a signed-off-by line signifying that you agree to the Developer Certificate of Origin: Signed-off-by: Random J Developer <random@developer.example.org>. This is meant to make sure that you agree that your change is distributed under the license (or licenses) of the project you’re contributing to.
• Anyone that is making a MR should have tested their change.
• Alert one of the maintainers to review the MR, ideally by using a @mention. Maintainers are listed in the DOAP file.
• If there is no single maintainer that knows the affected areas well, alert multiple ones.

Note

If you have a MR that depends on another outstanding MR (or if you only want feedback without a merge), prepend your MR title with “WIP”. For more info on WIP, see gitlab’s WIP documentation

Reviewing Merge Requests

Work In Progress merge requests serve only as a place for discussion, therefore no special procedure is required. A MR is valid even if the CI pipeline fails. For all other merge requests, please adhere to the following guidelines.

Anyone can comment and provide feedback on MRs. A special status is reserved for project members, who may become Reviewers. Reviewers take up the task of testing or providing feedback. It depends on their opinion whether the MR is accepted or not.

If you are listed in the DOAP file as a maintainer, developer, or helper, you can take up the role of a Reviewer on a merge request.

First off, save your time by skipping MRs which have a failing CI build. It’s the responsibility of the submitter to provide working code.

When multiple maintainers are interested in the outcome of the MR, please let them have an opportunity to speak, by using a @mention. This may happen for example when the MR is the outcome of a discussion or when it modifies areas maintained by multiple persons.

At the same time, it’s enough that one person tests a merge request.

To succesfully review someone’s MR, first indicate that you are reviewing the MR by making yourself the Assignee, or by saying that explicitly in the comments. Then:

• Build and test the newest version of the MR if no one else did that yet.
• Provide feedback in the MR discussion. This is where you would mention additional changes needed.

Once all reviewers are satisfied with the MR, merge it.

Do NOT merge the request if any of these are true:

• The MR has “WIP” in the title.
• The CI build of the current revision failed.
• No project member tested the current version of the MR.
• There are unresolved discussions.
• A maintainer was asked to take a look at the MR, but didn’t have the chance to speak yet.