Skip to content

Contributing

Jump to bottom
Daniel Massey edited this page Sep 20, 2025 · 5 revisions

Contributing

We welcome contributions of all types to MassOS. This document explains some of the ways you can contribute to MassOS, as well as rules and guidelines for contributions.

Community rules for contributions

MassOS is a heavily community-driven project. As such, we take the safety of the community very seriously. By contributing to MassOS, which includes participating in discussions and opening issues, you agree to abide by these rules to ensure that the community of the MassOS project remains welcoming and constructive. The MassOS developers and maintainers will also make every effort to follow these rules, and will enforce violations where necessary.

1️⃣ Treat people with respect. Everyone who is part of the MassOS community is expected to treat others with respect, and in exchange, be treated with respect by others. No harassment or discrimination of any kind is tolerated, including (but not limited to): racism, sexism, ageism, xenophobia, homophobia and transphobia. Criticism and debate is welcome, but should always be directed at ideas themselves, not the individual(s) who made/have them.

2️⃣ Respect the privacy of others. Do not leak or divulge personal and/or sensitive information about anyone without their explicit permission. This can include not only personal information, but also encryption/signing keys, if applicable.

3️⃣ Don't spread misinformation. Do not intentionally/knowingly spread misinformation of any kind. This includes, but is not limited to ideas, products, items, and individuals. If you unintentionally spread misinformation, always be open to corrections and acknowledge when you were in the wrong.

4️⃣ Keep discussions on-topic. In most situations, discussions should remain on-topic to the MassOS operating system and the MassOS project as a whole. Discussions which are not directly related to MassOS should be taken elsewhere on the internet. This includes general chat which is not relevant to MassOS, as well as opinions and debate which aren't to do with MassOS. Political and religious discussion is also outside the scope of the project, and should be taken elsewhere.

5️⃣ Speak in English or use machine-translation. While MassOS is designed to be accessible to anyone, the primary communication language within the project is English, and we are unfortunately not able understand or communicate in other languages. If you don't speak English, use a machine-translation tool, and we will do our best to accommodate, for example, by sticking to simple words and sentences.

In addition to the above rules, the GitHub Acceptable Use Policy also applies to all communication about, interaction with, and contribution to the MassOS project that takes place on GitHub.

Ways you can contribute

  • Providing a monetary donation to the project (see below), which funds future development and helps us cover hosting/maintainence costs.
  • Porting large software to MassOS which people might want, and which is not already available through Flatpak/Snap/AppImage or pre-built binaries available from the internet.
  • Finding and reporting issues. Even better, helping to fix issues that users have reported.
  • Writing documentation for the MassOS documentation.
  • Providing assistance/support to users who are facing issues.
  • Translating MassOS and the documentation into your native language.

Monetary contributions (donations)

The main way we accept monetary donations would be via cryptocurrency. This is the most privacy-respecting solution that does not rely on using proprietary software or services. The wallet addresses for each cryptocurrency we can receive are as follows (copy and paste them if possible, as any typos in the address may cause your money to be lost):

  • Bitcoin (BTC): 31kGcXCjh9XjA7yGPDpN37tgDiWoj3SFBi
  • Etherium (ETH): 0x92D8255bAf19aC82b1bd2D5a29d744065E47500B
  • Litecoin (LTC): MFgiiouxPJNCvyuEi1yYuYpBHjvf8FEJxu
  • Bitcoin Cash (BCH): 13h5iWDpnirr191a533nMj5zMHokyYV3LB
  • Etherium Classic (ETC): 0x5C64755b0Fa66aFe4eB84E4e6eEacC109bD92124
  • USDC (USDC): 0x6A21E86ee37275eA928fADD920776e23D67AFc4E
  • Dai (DAI): 0x1F34706757594A69D86b3d28B6c2D0c42F0724C1

The project as a whole does not accept payments via PayPal (which is a proprietary service), however the main developer personally does. If you therefore wish to donate via PayPal, you can use this link, whereby you can add a note to your donation stating that it is intended for the MassOS project.

We greatly appreciate, and provide gratitude in advance, for any monetary donation(s) you are willing to make to the project.

Guidelines for contributions

Please try to follow these guidelines when contributing to MassOS:

General guidelines

  • Only send modify and send pull requests to the development branch. We won't accept pull requests to the main branch.

Writing documentation

You can contribute to the MassOS documentation, by improving existing pages or adding extra pages, however please follow these guidelines:

  • Use good English - no grammatical errors are expected.
  • If editing existing pages, you can add enhancements/improvements, but don't change the main content.
  • If adding new pages, make sure they are about their own topic and not simply rephrasing what is already explained in other pages. New pages should also have a good reason to exist, for example, to discuss a topic which cannot easily be appended to an existing page.

Adding software to MassOS

These requirements apply to both feature requests and pull requests:

  • As stated in the LICENSE, we will only add software to the main MassOS system that is either in the public domain, or under a GPL-compatible license. We will not accept non-free programs, nor programs licensed under GPL-incompatible licenses. However we are willing to provide links to, and documentation for, such software, if it is supplied in a way that is not installed by default, but can be installed at runtime by the user.
  • As an exception to the above, some non-free firmware and software will be accepted under extreme circumstances. Read MassOS and Free Software for more information.
  • If you modify the build system to add software, please read the Build system section below.

Build system

TODO: This information needs expanding and clarification, especially with regards to stage 3 in the build system...

Modifying the build system is the best way to add extra packages to MassOS. Please see Building MassOS for full information about how the build system works, and what each script/file in the MassOS source tree is for. Please follow these guidelines when modifying/adding to the build system:

  • Always add your package to utils/builtins. Entries in this file must be in alphabetical order, lowercase, and not contain spaces (use a dash - instead.)
  • Keep the source URLs in alphabetical order according to the file name in source-urls. The same applies for checksums in source-urls.b2
  • It is preferable to avoid Sourceforge if at all possible, due to reliability issues with many of their server mirrors. If you must use Sourceforge download URLs, please use freefr.dl.sourceforge.net.
  • Patches should go in the patches/ directory, if they are required. Trivial issues may be easier fixed with a one-line sed, rather than an entire patch file.
  • Put any external systemd units required for packages in the directory utils/systemd-units. They will be automatically copied to the system directory at build time. This is only for packages which do not supply systemd units themselves.
  • In build-system.sh, build packages after any dependencies they require, and before any other package they can serve as an optional dependency for. If the other package can use your package as an optional dependency but doesn't by default, consider modifying the configuration/build flags of the other package so it can use it.
  • Building packages twice to workaround circular dependencies (even optional ones) is OK.
  • MassOS uses a unified filesystem structure (/bin, /lib and /sbin are symlinked to their user counterparts). Therefore, the installation prefix for packages can always be /usr.
  • Modern versions of MassOS now use a merged bin-sbin structure, where sbin is a symlink to bin. Therefore, you should always set --sbindir=/usr/bin (Autotools) or --sbindir=bin (Meson) on packages that would usually install binaries into sbin.
  • Always install any license files the package has. They are typically named "COPYING", "LICENSE", or variations of that. Install them after building with a command such as install -t /usr/share/licenses/<package-name> -Dm644 COPYING.
  • Prefer Meson and CMake over Autotools if a package supports either build system.

Clone this wiki locally