napcok/calamares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
15b476bb80
calamares/CONTRIBUTING.md
Adriaan de Groot 2b495a3781 Docs: update required versions
2023-09-10 21:40:37 +02:00

5.2 KiB
Raw Blame History

Contributing to Calamares

Welcome to Calamares! We're happy that you would like to add something to Calamares. This contribution guide should help you get started. The guide is not exhaustive: most of it points to other documents that you will need.

Code of Conduct

The Calamares community -- of developers, translators, and downstream (distro) users -- aims to be courteous, professional, and inclusive. Harrassment, discriminatory statements and abuse are not tolerated. In general, we apply the KDE Code of Conduct and the GNOME Code of Conduct (the rules of decent behavior in both communities are pretty much the same).

See the CoC section on the wiki for a longer text. To report a problem, please contact the maintainer, Adriaan de Groot, or the KDE Community Working Group.

Join the Conversation

GitHub Issues are one place for discussing Calamares if there are concrete problems or a new feature to discuss. Issues are not a help channel. Visit Matrix for help with configuration or compilation.

Regular Calamares development chit-chat happens in a Matrix room, #calamares:kde.org. Responsiveness is best during the day in Europe, but feel free to idle. Matrix is persistent, and we'll see your message eventually.

  • Join us on Matrix

General Guidelines

Pull Requests are welcome!

It is often a good idea to start a Pull Request early, with just work-in-progress, so that the overall approach can be discussed before you put a lot of work into something. Or file an issue describing what you would like to do.

If you are writing code, stick to the existing coding style and apply the coding-style tool before you commit. It's not my favorite style, but at least all of Calamares is consistent and the tool helps it stay that way.

If you are writing documentation, use en_US spelling.

If you are doing cool stuff, let us know (on Matrix or through issues).

Do fork Calamares to try new things, don't keep your fork to yourself, do upstream things as much as you can. When you make cool new things, it's best for the whole Calamares-using-community to build new things that are configurable and applicable to other distributions than your own. So keep other folk in mind. There is also the extensions repository for somewhat-more-specialized modules and examples.

Building Calamares

Up to date building-Calamares instructions are on the wiki.

Simple Build in Docker

You may have success with the Docker images that the CI system uses. Pick one (or both):

  • docker pull docker://opensuse/tumbleweed
  • docker pull kdeneon/plasma:user

Then start a container with the right image, from the root of Calamares source checkout:

  • docker run -ti --tmpfs /build:rw --user 0:0 -v .:/src opensuse/tumbleweed
  • docker run -ti --tmpfs /build:rw --user 0:0 -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=:0 -v .:/src kdeneon/plasma:user bash This starts a container with the chosen image (openSUSE Tumbleweed or KDE neon, here) with a temporary build directory in /build and the Calamares sources mounted as /src. KDE neon needs some extra settings to avoid starting a complete desktop.

Run the script to install dependencies: you could use deploycala.py or one of the shell scripts in .github/workflows to install the right dependencies for the image.

  • ./.github/workflows/nightly-opensuse-qt6.sh

Then run CMake (add any CMake options you like at the end) and ninja:

  • cmake -S /src -B /build -G Ninja
  • ninja -C /build

Dependencies

Main:

  • Compiler with C++17 support
  • CMake >= 3.16
  • Qt >= 5.15
  • yaml-cpp >= 0.5.1
  • KDE Frameworks KCoreAddons >= 5.78
  • Python >= 3.6 (required for some modules)
  • Boost.Python >= 1.72.0 (required for some modules)
  • KDE extra-cmake-modules >= 5.78 (recommended; required for some modules; required for some tests)

Individual modules may have their own requirements; these are listed in CMake output. Particular requirements (not complete):

  • fsresizer KPMCore >= 3.3 (>= 4.2 recommended)
  • partition KPMCore >= 3.3 (>= 4.2 recommended)
  • users LibPWQuality (optional)

Configuring and Deploying Calamares

Deployment instructions are on the wiki.

Translating Calamares

Calamares translations are done on Transifex. The translator's guide on the wiki explains how to get involved there.

Testing Calamares

There is a testing guide on the wiki. It is possible to test most parts of Calamares in isolation, but the real proof of the pudding comes with an actual installation of some distro using Calamares.

The UI components should get some specific usability testing instructions soon.