~anjan/sxmo-docs-stable

ref: fbaf318cd482c5ececc13a07106a3b0855a02f63 sxmo-docs-stable/CONTRIBUTING.md -rw-r--r-- 5.2 KiB
fbaf318c — Anjandev Momi move development version docs to new line, add link to system guide 6 months ago

#Sxmo: Simple X Mobile - Contributing

Project Overview | Documentation | Install Guide | User Guide | System Guide | Contributing | Images | Demo Video

Documentation (Development Version)

The Sxmo project from a development point of view is a combination of a few different components:

  1. sxmo-utils: A catchall repository for scripts, configuration files, and C programs that hold Sxmo together. This contains things like the modem scripts, menu scripts, screenlock program, setuid programs for controlling the PP LEDs, brightness, etc, and all other scripts.
  2. lisgd: A custom piece of software for gestures built from scratch for Sxmo
  3. Suckless forks: Forks of Suckless software which has been mobile optimized and designed to fit within the larger Sxmo project
  4. sxmo-image-builder: CI that builds images for the Pinephone on sr.ht infra via pmbootstrap

All of the Sxmo project source repositories can be viewed at:

Project source repositories

#Testing Nightly

We always need help testing the latest development version of sxmo. To help test sxmo's latest development version, you can run sxmo_build_all.sh from: ~mil/sxmo-build.

Please report bugs to the bug tracker or join us in irc for help.

#Submitting Bugs or Feature Requests

We use the bug tracker at:

https://todo.sr.ht/~mil/sxmo-tickets

Please search the existing tickets before submitting a new ticket. You are free to put in feature requests here or pull tickets off here to get ideas for patches.

#Submitting Patches or General Discussion

We use a single mailing list for patch submission and discussion of the above subcomponents of the Sxmo project.

The mailing list is at:

https://lists.sr.ht/~mil/sxmo-devel

If you're new to development using git-send-email don't be discouraged and please still contribute!

#Quick Start

  1. Change the default subject prefix from "PATCH" to "PATCH " by running this command (only needed once). 
    $ git config --local format.subjectPrefix "PATCH <NAME-OF-REPO>"
    If you wanted to submit a change for sxmo-utils, change <NAME-OF-REPO> in the command above to sxmo-utils.
  2. Rebase your commits on top of the latest master.
  3. Send the patch to the mailing list: 
    $ git send-email --to="~mil/sxmo-devel@lists.sr.ht" origin/master

Also, you can check out the guide at: https://git-send-email.io/ for a guided tutorial on using git-send-email.

#IRC Channel

Our IRC channel for general adhoc development discussion is:

  • #sxmo on irc.oftc.net
  • #sxmo-offtopic on irc.oftc.net

#Information for Maintainers

#Releases: Steps for cutting a new release of an Sxmo package

Steps:

  1. Tag the release in git (sxmo-utils, sxmo-dwm, etc.)
    1. Include the changelog in the tag message
  2. Send a pull request to pmaports to update the changed sxmo packages
  3. Send an email to the mailing list (sxmo-announce) containing atleast the following info:
    1. New Sxmo release will be available soon!
    2. Description of which repos have been updated (sxmo-utils, sxmo-dwm, etc.)
    3. A paragraph detailing major changes
    4. An Annotated Summary of Changes - Thank the contributors
    5. Description of breaking changes
    6. Where to get the new images or how to update from an existing release
    7. Any other pmos related issues (update-u-boot, updating modem firmware, etc.)

Notes on Package Versioning: Versioning numbers for suckless forks follow the scheme: sucklessv.sxmov. For example, with the dmenu fork, checkout 4.9 as upstream-4.9 and commit new versions as 4.9.x; wherein x is the Sxmo version.

#Accepting a Patch

  1. Contributor submits a patch
  2. Maintainer A assign themselves to the patch and tests the patch
  3. If the patch passes testing, Maintainer A can ask Maintainer B if they're unsure about the code quality.
  4. Sign the commit with git am -s

Note: Unless the change is trivial, the maintainer must send their change to mailing list to be reviewed by another maintainer or a member of the sxmo community

Notes on Stable Release Flow:

New releases must be in Alpine Edge for a certain amount of time for them to be accepted into postmarketOS's stable releases and service packs.

As such, the flow is as follows:

  1. Push new release to Alpine Edge (aports) unless the package is in pmaports only (ie. ui packages)
  2. Wait for a postmarketOS stable or service pack release. When a new release of pmOS is imminent, copy APKBUILDS from aports into pmaports.