Commit fcf54e26 authored by David Boddie's avatar David Boddie

Merge branch 'master' into restructuring1

parents 39816396 02d28e05
......@@ -13,7 +13,8 @@ All APIs developed to enable these core apps will also be publicly available and
**Must Have Applications**
Applications that must be part of the Librem 5 launch in January 2019.
Applications that must be part of the Librem 5 launch.
|
|
......
......@@ -8,3 +8,5 @@ The `official flatpak documentation <http://docs.flatpak.org/en/latest/>`_ shoul
purism@pureos:~$ sudo apt-get install flatpak flatpak-builder
purism@pureos:~$ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
purism@pureos:~$ flatpak install flathub org.gnome.Platform//3.30
.. note:: While this documentation will direct you to the stable flatpak GNOME repository, it will be common and often required to use the gnome-nightly repository instead, for example to access the master branches of GNOME Sdk and Platform. These master branches may be required to build projects such as Calls. For more information, see the `Nightly GNOME Apps <https://wiki.gnome.org/Apps/Nightly>`_ page.
......@@ -25,7 +25,7 @@ First, checkout the `official documentation for GNOME Builder <https://builder.r
Setting up QEMU on Debian based systems
***************************************
Since Builder relies on statically linked qemu binaries, you will either need to run an OS that already does this for you (like Fedora) or fix up your Debian workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by PureOS/Debian. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
Since Builder relies on statically linked qemu binaries, you will either need to run an OS that already does this for you (like Fedora, Debian Buster, or PureOS) or fix up your Debian stable workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by your OS. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
To perform these operations, you will need to be the root user (sudo is not good enough).
......
.. _gtk+:
.. _GTK+ website : https://www.gtk.org/
.. _GTK+ 3 documentation : https://developer.gnome.org/gtk3/stable/
.. _GTK+ Inspector : https://wiki.gnome.org/Projects/GTK+/Inspector
.. _selection mode : https://developer.gnome.org/hig/stable/selection-mode.html.en
......@@ -18,10 +19,12 @@
.. _GtkLabel ellipize property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--ellipsize
.. _GtkLabel wrap property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap
.. _GtkLabel wrap-mode property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--wrap-mode
.. _GtkLabel xalign property : https://developer.gnome.org/gtk3/stable/GtkLabel.html#GtkLabel--xalign
.. _GtkSeparator : https://developer.gnome.org/gtk3/stable/GtkSeparator.html
.. _GtkSizeGroup : https://developer.gnome.org/gtk3/stable/GtkSizeGroup.html
.. _libhandy : https://source.puri.sm/Librem5/libhandy
.. _libhandy website : https://source.puri.sm/Librem5/libhandy
.. _libhandy documentation : http://honk.sigxcpu.org/projects/libhandy/doc/
.. _HdyHeaderGroup : https://honk.sigxcpu.org/projects/libhandy/doc/HdyHeaderGroup.html
.. _HdyLeaflet : https://honk.sigxcpu.org/projects/libhandy/doc/HdyLeaflet.html
.. _HdyTitleBar : https://honk.sigxcpu.org/projects/libhandy/doc/HdyTitleBar.html
......@@ -32,8 +35,10 @@ GTK+
====
`GTK+ <GTK+ website_>`_ is the graphical application framework used to develop all GNOME applications. This section presents tips and tricks with GTK+ to help you develop great adaptive applications for GNOME, for general GTK+ and GNOME development resources please check the :ref:`gnome_resources` page.
Don't forget to check its `documentation <GTK+ 3 documentation_>`_ out.
libhandy_ is a widget library for GTK+. It contains widgets useful for both phone applications and adaptive applications and it is going to be used in that page as an extension to GTK+.
`libhandy <libhandy website_>`_ is a widget library for GTK+. It contains widgets useful for both phone applications and adaptive applications and it is going to be used in that page as an extension to GTK+.
Don't forget to check its `documentation <libhandy documentation_>`_ out.
.. warning:: From now on, this section assumes you are familiar with the basics of GTK+ application development. It also assumes you are using GTK+ 3.24.1 or newer and libhandy 0.0.4 or newer as these versions received improvements required for adaptive apps to function properly.
......@@ -68,6 +73,8 @@ A GtkLabel_ can prevent your application's UI from reaching really small sizes,
Allowing your label to ellipsize will cut a part of your string when there isn't enough space for it, you can enable it and choose which part will be cut with the `GtkLabel ellipize property`_. Use it if you really need your label to be on a single line.
.. note:: If you allow your label to be elipsized, make sure that its `xalign property <GtkLabel xalign property_>`_ matches its justification or your label may not be properly aligned when ellipsized: 0 for left, 1 for right, or 0.5 for center.
Letting your label wrap will preserve the integrity of the text at the expense of more height, you can enable it with the `GtkLabel wrap property`_ and choose how to wrap with the `GtkLabel wrap-mode property`_.
.. note:: By allowing the label to wrap, it will always request enough height when fully wrapped. Consider putting your label or a widget containing it into a scrollable window to avoid height becoming a problem.
......
......@@ -36,12 +36,17 @@ Matrix Chat Rooms
Join our Matrix chat rooms using your Matrix login:
Librem 5 specific:
* `community/librem-5 <https://matrix.to/#/#community-librem-5:talk.puri.sm>`_ (ID !BSqRHgvCtIsGittkBG:talk.puri.sm) : For Librem 5 development chatter
* `community/librem-5 <https://matrix.to/#/#community-librem-5:talk.puri.sm>`_ (ID: !BSqRHgvCtIsGittkBG:talk.puri.sm) : For Librem 5 development chatter
* `Phosh <https://matrix.to/#/#phosh:talk.puri.sm>`__ (ID: !CBfWYXjnVtAdBQWXVI:talk.puri.sm): For discussions regarding `phosh <https://source.puri.sm/Librem5/phosh>`__
* `Libhandy <https://matrix.to/#/#libhandy:talk.puri.sm>`__ (ID: !nrNOrVsRZxzaDdspgs:talk.puri.sm): For discussions regarding the `libhandy <https://source.puri.sm/Librem5/libhandy>`__ GTK+ library
* `Chatty <https://matrix.to/#/#chatty:talk.puri.sm>`__ (ID: !zaQzHCRfyTXoMIqcxq:talk.puri.sm): For discussions regarding the `chatty <https://source.puri.sm/Librem5/chatty>`__ messaging application
* `Calls <https://matrix.to/#/#calls:talk.puri.sm>`__ (ID: !ghzbolmVJyjKZTxyfl:talk.puri.sm): For discussions regarding the `calls <https://source.puri.sm/Librem5/calls>`__ application
Community rooms for non-Librem 5 discussions:
* `community/pureos <https://matrix.to/#/#community-pureos:talk.puri.sm>`_ (ID !bGtSETqkYFOebMtlfH:talk.puri.sm) : For discussions around PureOS in general
* `community/purist <https://matrix.to/#/#community-purist:talk.puri.sm>`_ (ID !RkGDRtKCBzjnWMEGMV:talk.puri.sm) : For Purist Services
* `community/general <https://matrix.to/#/#community-general:talk.puri.sm>`_ (ID !aXWDJNTtEfhSXdPoQT:talk.puri.sm) : For questions that are not obviously related to the Librem 5, PureOS, or Purist Services
* `community/pureos <https://matrix.to/#/#community-pureos:talk.puri.sm>`_ (ID: !bGtSETqkYFOebMtlfH:talk.puri.sm) : For discussions around PureOS in general
* `community/purist <https://matrix.to/#/#community-purist:talk.puri.sm>`_ (ID: !RkGDRtKCBzjnWMEGMV:talk.puri.sm) : For Purist Services
* `community/general <https://matrix.to/#/#community-general:talk.puri.sm>`_ (ID: !aXWDJNTtEfhSXdPoQT:talk.puri.sm) : For questions that are not obviously related to the Librem 5, PureOS, or Purist Services
* `community/heads <https://matrix.to/#/#community-heads:talk.puri.sm>`_ (ID: !BSPqgzeiCeaSBayTLM:talk.puri.sm): For questions regarding HEADS
If you do not already have a Matrix account, please visit `Matrix's website
<https://matrix.org>`_ to choose a Matrix client where you can register. Once
......
......@@ -3,6 +3,11 @@
Contributing
============
.. toctree::
:hidden:
Contributing/Translations
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 <https://source.puri.sm/Librem5/>`_. For example, if you find an issue with the documentation, you can file an issue under the `developer docs <https://source.puri.sm/Librem5/developer.puri.sm/issues>`_ 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 <https://source.puri.sm/Librem5/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 <https://source.puri.sm/Librem5/>`_ first before opening an issue under `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues>`_.
......@@ -14,7 +19,7 @@ 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 are :ref:`filing an issue <issues>`, 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.
......
......@@ -57,3 +57,42 @@ Some examples of *other application* issues would be:
* You wish there to be a certain application available for the phone and want to file an issue about it in hopes someone creates it. Please follow the wishlist template provided in the Apps_issues repo when filing out these types of wishlist item issues.
If you would like to work on any of these issues, please see our :ref:`working on issues <working-on-issues>` section.
Using Labels
------------
There are global labels that are available to all projects and there are project-specific labels. Here is some info on the available labels and their suggested usage.
.. note:: Librem 5 issues will be closed only when the fix is being shipped in a recent image build.
Global Labels
^^^^^^^^^^^^^
To gauge how serious the issue is, we've provided severity labels that correspond to the same `bug severities used by Debian <https://www.debian.org/Bugs/Developer#severities>`_:
* **critical** - makes unrelated software on the system (or the whole system) break, or causes serious data loss, or introduces a security hole on systems where you install the package
* **grave** - makes the package in question unusable or mostly so, or causes data loss, or introduces a security hole allowing access to the accounts of users who use the package
* **serious** - the package has an issue with licensing (non-free), privacy, or security, or (in the package maintainer's or release manager's opinion) makes the package unsuitable for release
* **important** - a bug which has a major effect on the usability of a package, without rendering it completely unusable to everyone
* **normal** - the default value, applicable to most bugs
* **minor** - a problem which doesn't affect the package's usefulness, and is presumably trivial to fix
* **wishlist** - for any feature request, and also for any bugs that are very difficult to fix due to major design considerations
Please add an appropriate severity label to the issue you are filing.
There are also some other optional labels that are globally available to all projects:
* **needsupstreamwork** - the issue has an upstream component that will need to be fixed
* **fixedupstream** - the issue has been fixed upstream but the fix has not trickled down to the Librem 5 project yet
* **helpwanted** - anyone can sign up to work on this issue
* **needsdesign** - the issue is a good idea but the implementation and next steps needs to be investigated and identified
* **wontfix** - the issue will not be resolved and a reason should be in the comments
Please add any of the optional labels that make sense for the issue being filed.
Project Labels
^^^^^^^^^^^^^^
Some projects have some project-specific labels defined, most notably the `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues/issues>`_ repository. Because the Apps_issues repo contains issues about many different projects that do not have their own repositories, there are labels created to identify each application. This allows issues that all relate to say a weather application to be grouped under the "weather" label.
Please add any project specific labels that make sense.
.. _translations:
Translations
============
A common way of contributing is by adding translations to our various projects. The translations are contributed via a public `Zanata server <https://translate.zanata.org/>`_. If you are interested in contributing a tranlsation, here is the process:
Create an account
^^^^^^^^^^^^^^^^^
The public Zanata server requires you to first create an account with them. Once you have done this, log in and you will be taken to your dashboard.
Join a language team
^^^^^^^^^^^^^^^^^^^^
In order to have write access to a certain language, you will first need to join the corresponding language team. On your dashboard, you should see the "Join a language team" link where you can search for and join a specific team.
Find our projects
^^^^^^^^^^^^^^^^^
Once you're a part of a language team, click the "Explore" icon on the left panel to search for our projects. For example, you can search for "phosh" and you should find our phosh project. The page for the project should list versions so click the latest version listed to access the list of languages available for translation.
.. image:: phosh-project-page.png
:width: 700px
:height: 200px
:align: center
Add a translation
^^^^^^^^^^^^^^^^^
Select the language for which you wish to add a translation (under the Languages column) and then select the project name (under the Documents column).
.. image:: phosh-get-to-translation.png
:width: 700px
:height: 200px
:align: center
Now you should have the translation page displayed where you can see the English text on the left half of the screen and add a translation to the right half of the screen (with suggestions on the bottom part of the screen).
.. image:: phosh-translate-page.png
:width: 700px
:height: 300px
:align: center
Note that if you are not part of the corresponding language team (or an admin for the project), then you will not be able to enter text for translating these fields.
What's next?
^^^^^^^^^^^^
Every time the Librem 5 team releases a new version of the project, the new translations will be grabbed from Zanata. By adding a translation in Zanata, you are creating a .po file that will get picked up in the next release of the project.
......@@ -15,8 +15,8 @@
<maintainer>
<foaf:Person>
<foaf:name>Heather Ellsworth</foaf:name>
<foaf:mbox rdf:resource="mailto:heather.ellsworth@puri.sm" />
<foaf:name>David Boddie</foaf:name>
<foaf:mbox rdf:resource="mailto:david.boddie@puri.sm" />
</foaf:Person>
</maintainer>
</Project>
Markdown is supported
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