Commit 00ce7bc8 authored by Heather Ellsworth's avatar Heather Ellsworth
Browse files

Merge branch 'contributing' into 'master'

Merge Request Guidelines

See merge request Librem5/!16
parents 03bca527 d6fc77fd
.. _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 specific projects <>`_ first before opening an issue under `Apps_issues <>`_.
If you wish to own an issue, 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 `here <>`_ but here is an example file you can modify to match your project::
<?xml version="1.0" encoding="UTF-8"?>
<Project xmlns:rdf=""
<name>YOUR PROJECT</name>
<shortname>YOUR PROJECT</shortname>
<homepage rdf:resource="LINK TO CODE" />
<license rdf:resource="" />
<foaf:name>MAINTAINER'S NAME</foaf:name>
<foaf:mbox rdf:resource="mailto:MAINTAINER'S EMAIL" />
<foaf:name>FREQUENT REVIEWER NAME</foaf:name>
<foaf:mbox rdf:resource="mailto:FREQUENT REVIEWER EMAIL" />
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 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
By making a merge request (MR) 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 the merge request, add a sign off line signifying that you agree that your work is used under the license or project being contributed to: ``Signed-off-by: Random J Developer <>``
* Anyone that is making a MR should have tested their change.
* Alert someone to review the MR.
* While you may require more than one reviewer (depends on the change), only one tester is required.
.. 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 `the WIP documentation <>`_
Reviewing Merge Requests
Follow these steps to succesfully review someone's MR:
* Build and test the change in question.
* Provide feedback in the MR discussion. This is where you would mention additional changes needed.
* Once all changes are approved, the reviewer should acknowledge that they tested it in the MR discussion.
* Merge the request.
Do NOT merge the request if any of these are true:
* The MR has "WIP" in the title. These MRs do not have to pass tests and reviewers are meant to provide feedback only.
* If no one has built and tested the change
* If there are unresolved discussions.
Librem 5 Docs
.. toctree::
.. image:: images/purism_logo.png
:width: 200px
:height: 55px
......@@ -23,14 +11,17 @@ Intro
Welcome to the Librem 5 documentation! This site contains instruction and examples to help you accomplish your goals with the Librem 5 dev kit and phone.
.. toctree::
:caption: Table of Contents
* :ref:`design` (to be implemented) - Take a look at the expected look and feel of the Librem 5 phone. As an app developer, you can get an idea of how apps fit into the overall user interface.
* :ref:`phosh` - Learn how to setup the wlroots-based phone shell for development.
* :ref:`plamo` - Walkthrough to setup Plasma Mobile.
* :ref:`app_development` - Find out all about how to make, build, deploy, and publish applications.
* :ref:`volunteering` - Find out how you can get involved and help improve the project.
* :ref:`resources` - Useful external resources.
* :ref:`genindex` - Index of used terms.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment