GNOME Project Handbook

https://handbook.gnome.org
Admin
The GNOME Project Handbook provides comprehensive documentation for new and existing contributors to...
Tokens:23,951
Snippets:426
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run the Newly Installed Module

Source: https://handbook.gnome.org/development/toolbx.html

After installation, stop any running instances of the module and then execute the newly built version.

```bash
⬢ killall gnome-clocks && gnome-clocks

```

--------------------------------

### Example .gitlab-ci.yml for gnome-font-viewer

Source: https://handbook.gnome.org/maintainers/release-pipeline.html

This example shows a `.gitlab-ci.yml` configuration for a project that uses the Flatpak CI template and the release service component. It extends the base Flatpak configuration and defines variables for the build.

```yaml
include:
  - project: "gnome/citemplates"
    file: "flatpak/flatpak_ci_initiative.yml"
  - component: "gitlab.gnome.org/GNOME/citemplates/release-service@master"
    inputs:
      dist-job-name: "flatpak"

flatpak:
  extends: '.flatpak'
  variables:
    MANIFEST_PATH: 'build-aux/flatpak/org.gnome.font-viewerDevel.json'
    RUNTIME_REPO: 'https://sdk.gnome.org/gnome-nightly.flatpakrepo'
    FLATPAK_MODULE: "gnome-font-viewer"
    APP_ID: 'org.gnome.font-viewerDevel'
    BUNDLE: 'org.gnome.font-viewerDevel.flatpak'

nightly:
  extends: '.publish_nightly'
  dependencies: ['flatpak']
  needs: ['flatpak']

```

--------------------------------

### Install Build Dependencies

Source: https://handbook.gnome.org/development/toolbx.html

Navigate into the cloned module directory and use 'dnf builddep' to install the necessary dependencies for building on Fedora containers.

```bash
⬢ cd gnome-clocks
⬢ sudo dnf builddep -y gnome-clocks

```

--------------------------------

### Install the Module

Source: https://handbook.gnome.org/development/toolbx.html

Install the compiled module using Meson. This action will overwrite any existing version of the module within the container's '/usr' directory.

```bash
⬢ sudo meson install -C builddir

```

--------------------------------

### Compile the Module

Source: https://handbook.gnome.org/development/toolbx.html

Compile the module using Meson, referencing the build directory specified during the setup phase.

```bash
⬢ meson compile -C builddir

```

--------------------------------

### Install Flatpak Debug Extensions and SDK

Source: https://handbook.gnome.org/issues/stack-traces.html

Install the debug extension, SDK, and SDK debug extension for the Flatpak app and its runtime to enable detailed stack traces.

```bash
$ flatpak install org.gnome.Epiphany.Debug
$ flatpak install org.gnome.Sdk
$ flatpak install org.gnome.Sdk.Debug
```

--------------------------------

### Example Stack Trace Output

Source: https://handbook.gnome.org/issues/stack-traces.html

This shows the beginning of a stack trace generated with 'bt full', providing function call information and line numbers.

```text
#0  __strlen_evex () at ../sysdeps/x86_64/multiarch/strlen-evex-base.S:81
#1  0x00005618113dcc25 in populate_completions_model (source_object=<optimized out>, res=<optimized out>, user_data=<optimized out>)
    at ../src/nautilus-location-entry.c:421
        completion = 0x0
        i = 0
        iter = {stamp = 1291743408, user_data = 0x7f6924002720, user_data2 = 0x7ffee626dd80, user_data3 = 0x7f6952eeed2d <g_queue_push_head+29>}
        current_dir_strlen = 16
        task = <optimized out>
        completer_data = <optimized out>
        entry = 0x56184e3b2750 [NautilusLocationEntry]
        priv = 0x56184e3b2570
        error = 0x0
        completions = 0x7f692405cc20
        is_relative = <optimized out>
#2  0x00007f69530d921c in g_task_return_now (task=0x56184e319a20 [GTask]) at ../gio/gtask.c:1363
#3  0x00007f69530d9255 in complete_in_idle_cb (task=task@entry=0x56184e319a20) at ../gio/gtask.c:1377

```

--------------------------------

### Example tag message

Source: https://handbook.gnome.org/maintainers/making-a-release.html

When creating an annotated tag, the editor will prompt for a message. This example shows the expected format for the tag message, including the project name and version.

```text
GNOME Foo 43.0


```

--------------------------------

### Enter a Toolbx Container

Source: https://handbook.gnome.org/development/toolbx.html

Enter an existing Toolbx container to start working inside it. The prompt will change to indicate you are inside the container.

```bash
$ toolbox enter gnome

```

--------------------------------

### Configure the Build with Meson

Source: https://handbook.gnome.org/development/toolbx.html

Configure the build process using Meson, specifying the build directory and the installation prefix. Building to '/usr' within the container will overwrite existing versions.

```bash
⬢ meson setup builddir --prefix=/usr

```

--------------------------------

### Update Flatpak Installations

Source: https://handbook.gnome.org/issues/stack-traces.html

Run 'flatpak update' to ensure that the installed debug extensions precisely match the versions of the runtime and application.

```bash
$ flatpak update
```

--------------------------------

### Install Missing Package Dependency

Source: https://handbook.gnome.org/development/toolbx.html

Installs a specific package dependency required for the module to build. Use this command when the build output indicates a missing 'foo-2.0' package or similar.

```bash
sudo dnf install 'pkgconfig(foo-2.0)'
```

--------------------------------

### Example NEWS file format

Source: https://handbook.gnome.org/maintainers/making-a-release.html

A sample format for the NEWS file, which is used by packagers and integrators. It can be more verbose than AppStream metadata.

```text
Version 43.0
------------
* Dependency update
* Some change
* A bug fix
* Small maintenance tasks
* Translation updates


```

--------------------------------

### C Code with SPDX License and Copyright

Source: https://handbook.gnome.org/development/legal.html

Example of C code file headers following REUSE guidelines, including SPDX license and copyright text tags.

```c
/* your-project-file.c
 * 
 * SPDX-License-Identifier: LGPL-2.1-or-later
 * SPDX-FileCopyrightText: 2024 Your Name
 * SPDX-FileCopyrightText: 2025 Another Contributor
 */

```

--------------------------------

### Example Commit Message Structure

Source: https://handbook.gnome.org/development/commit-messages.html

Illustrates the standard structure of a commit message, including a summary line, a detailed body, and issue references.

```git
tag: Short explanation of the commit

Longer explanation explaining exactly what's changed and why,
whether
any external or private interfaces changed, what issue were fixed (with
issue number if applicable) and so forth. Be concise but not too brief.

Closes #1234

```

--------------------------------

### Python Code with SPDX License and Copyright

Source: https://handbook.gnome.org/development/legal.html

Example of Python code file headers adhering to REUSE guidelines, featuring SPDX license and copyright text tags.

```python
# your-project-file.py
# 
# SPDX-License-Identifier: GPL-3.0-or-later
# SPDX-FileCopyrightText: 2025 Your Name

```

--------------------------------

### Low Quality Description Response

Source: https://handbook.gnome.org/issues/stock-responses.html

Use this response when an issue report lacks a complete and understandable description. It guides the reporter to the issue reporting guide for more details.

```text
Thanks for taking the time to report this issue. Unfortunately, this report isn't very useful because it doesn't include a complete and easy to understand description of the issue. Please see the [issue reporting guide](https://handbook.gnome.org/issues/reporting.html) and update the issue report to include a more detailed description.

```

--------------------------------

### Create a Directory for Source Code

Source: https://handbook.gnome.org/development/toolbx.html

Inside the Toolbx container, create a directory to store the source code of the modules you intend to build.

```bash
⬢ mkdir checkout && cd checkout

```

--------------------------------

### Create a Toolbx Container

Source: https://handbook.gnome.org/development/toolbx.html

Use this command to create a new Toolbx container. The container will be based on the host operating system's latest version by default. You can specify a different distribution and release using --distro and --release options.

```bash
$ toolbox create gnome

```

--------------------------------

### Get Flatpak Runtime ID

Source: https://handbook.gnome.org/issues/stack-traces.html

Use 'flatpak info <app-id> | grep Runtime' to identify the runtime ID used by a Flatpak application.

```bash
$ flatpak info org.gnome.Epiphany | grep Runtime
Runtime: org.gnome.Platform/x86_64/master
```

--------------------------------

### Build Project with Meson

Source: https://handbook.gnome.org/development/toolbx.html

Compiles the project after making code changes. Ensure you have run this command to include your modifications in the build.

```bash
meson compile -C builddir
```

--------------------------------

### Hackfest Event Page Template

Source: https://handbook.gnome.org/events/hackfests/template.html

Use this Markdown template as a starting point for creating pages for GNOME hackfests. It includes placeholders for all essential event details.

```markdown
<Hackfest Title> <Year>
===

* Location: city, country
* Dates:
* Primary contact: name & email
* Secondary contact: name & email

## Description

What will happen at the hackfest. Who it is intended for. What the format will be.

## Agenda

* Topic 1
* Topic 2
* Topic 3

## Traveling

How to get to the city the event takes place.

[Travel sponsorship](https://handbook.gnome.org/events/travel.html) is available for those who need it.

### By plane:

* List nearby airports and common flight connections.

### By train:

* List local train station or bus routes.

### By boat (if applicable):

* List nearby ports.

## Venue

* Address of the venue
* Rooms

Directions (if necessary).

## Attendees

| Name            | Role and interests      | Dietary restrictions | Arrives | Departs |
|-----------------|-------------------------|----------------------|---------|---------|
|                 |                         |                      |         |         |

## Blog posts

Please list blog posts about the hackfest below:

* ...
* ...
* ...

## Code of Conduct

Hackfest attendees are required to follow the [GNOME Code of Conduct](https://conduct.gnome.org/). Code of conduct incidents can be reported to the Code of Conduct Committee.

```

--------------------------------

### Generate Stack Trace for Flatpak App

Source: https://handbook.gnome.org/issues/stack-traces.html

Use 'flatpak-coredumpctl <app-id>' followed by '(gdb) bt full' to obtain a stack trace for a Flatpak application.

```bash
$ flatpak-coredumpctl org.gnome.Epiphany
(gdb) bt full
```

--------------------------------

### Minimal .gitlab-ci.yml for Release Pipeline

Source: https://handbook.gnome.org/maintainers/release-pipeline.html

This is a basic configuration for a release pipeline using a GNOME CI/CD component. It defines stages and a job to build and artifact the release tarball.

```yaml
include:
  - component: "gitlab.gnome.org/GNOME/citemplates/release-service@master"
    inputs:
      job-stage: "release"
      dist-job-name: "build-release-tarball"              # <1.>

stages:
  - "build"
  - "release"

build-release-tarball:                                    # <2.>
  stage: "build"
  variables:
    MESON_BUILD_DIR: "_build"
  script:
    - meson setup "${MESON_BUILD_DIR}"
    - meson dist -C "${MESON_BUILD_DIR}" --include-subprojects
    - cp -r "${MESON_BUILD_DIR}/meson-dist/" "${CI_PROJECT_DIR}/public-dist/"
  artifacts:
    name: "${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
    when: "always"
    paths:
      - "public-dist"                                     # <3.>

```

--------------------------------

### Clone a Module Repository

Source: https://handbook.gnome.org/development/toolbx.html

Use Git to clone the source code repository for the GNOME module you wish to build.

```bash
⬢ git clone https://gitlab.gnome.org/GNOME/gnome-clocks.git

```

--------------------------------

### Import Local Project to GNOME GitLab

Source: https://handbook.gnome.org/infrastructure/gitlab/new-gnome-project.html

Use this command to add the GNOME GitLab repository as a remote and push all local branches and tags to the new repository. Ensure you have GNOME developer access and an SSH key uploaded to GitLab.

```shell
git remote add origin git@gitlab.gnome.org:GNOME/repository-name.git
git push origin --all
```

--------------------------------

### Configure Evolution for GNOME Email Alias

Source: https://handbook.gnome.org/infrastructure/email-aliases.html

Set up Evolution to send emails using your @gnome.org alias. Ensure 'Receiving Email' is set to 'none' and configure SMTP settings with authentication.

```text
Email Address: email alias (e.g name@gnome.org)
Receiving Email: none

Sending Mail: smtp.gnome.org, port 587 (TLS)
  * Encryption method: STARTTLS after connecting
  * Server requires authentication
    * Authentication type: PLAIN
    * Username: your GNOME Account username
```

--------------------------------

### Check debuginfod URL Configuration

Source: https://handbook.gnome.org/issues/stack-traces.html

Confirm if debuginfod is enabled by checking the DEBUGINFOD_URLS environment variable. A URL indicates that debuginfod is configured, which is necessary for fetching debugging symbols.

```bash
$ echo $DEBUGINFOD_URLS

```

--------------------------------

### List Flatpak Applications

Source: https://handbook.gnome.org/issues/stack-traces.html

Use 'flatpak list' to find the Application ID of the Flatpak app you want to generate a stack trace for.

```bash
flatpak list
```

--------------------------------

### Create and sign an annotated Git tag

Source: https://handbook.gnome.org/maintainers/making-a-release.html

Use git-evtag for strong signing guarantees when creating an annotated tag for a release. If git-evtag is unavailable, use the basic git tag -s or git tag -a.

```bash
git evtag sign <tag>
```

```bash
git tag -s <tag>
```

```bash
git tag -a <tag>
```

--------------------------------

### Generate Stack Trace with coredumpctl and gdb

Source: https://handbook.gnome.org/issues/stack-traces.html

Use coredumpctl to access the latest core dump and gdb to generate a full stack trace. This method requires systemd-coredump and debuginfod to be enabled. You will be prompted to enable debuginfod and continue without paging.

```bash
$ coredumpctl gdb

```

```gdb
(gdb) bt full

```

--------------------------------

### No Activity in a Year Response

Source: https://handbook.gnome.org/issues/stock-responses.html

Use this response for issues with no activity for a year, indicating the version is unsupported and suggesting checking recent versions. It also informs about the issue closing after 6 weeks without feedback.

```text
This issue was reported against a version which is not supported anymore. Developers are no longer working on this version. Please check if the issue you reported is present in a recent version of GNOME and update this report by adding a comment. Thank you again for reporting this and sorry that it could not be fixed for the version you originally used here.

Without feedback this report will be closed after 6 weeks.

```

--------------------------------

### Clean Build Directory

Source: https://handbook.gnome.org/development/toolbx.html

Forces a complete rebuild of the project by cleaning the build directory. Use this if changes are not reflected after recompiling.

```bash
meson compile -C builddir --clean
```

--------------------------------

### Create and Push a Stable Branch

Source: https://handbook.gnome.org/maintainers/branches.html

Use this command to create a new stable branch based on 'main' and push it to the remote repository. The '-u' option sets the upstream tracking for the new branch.

```bash
$ git branch gnome-45 main
$ git push -u origin gnome-45

```

--------------------------------

### Test SSH Connection to GNOME GitLab

Source: https://handbook.gnome.org/infrastructure/ssh-keys.html

Tests the SSH connection to GNOME GitLab to verify that the configuration is correct and authentication is working.

```bash
$ ssh -T git@gitlab.gnome.org
Welcome to GitLab, @yourusername!

```

--------------------------------

### Obsolete Version Response

Source: https://handbook.gnome.org/issues/stock-responses.html

Use this response when an issue is reported against an old, unsupported version of GNOME. It recommends upgrading and suggests reopening the bug with a newer version.

```text
Thanks for taking the time to report this issue. Unfortunately, you are using a version that is old and is no longer supported. GNOME developers are no longer working on that version, so unfortunately there will not be any bug fixes for the version that you use. We recommend that you upgrade to a newer version of GNOME. Please feel free to reopen this bug if the problem still occurs with a newer version.

```
Tokens:
Raw