On this page you can learn how to contribute to Boxes. If you are interested in general information about this app, please visit the Apps for GNOME page.
The original text in apps is usually written in American English. The translation into other languages can be added by translators separately. The translation usually encompasses the apps’ user interface as well as the metadata shown in places like Software or apps.gnome.org. Common abbreviations used in this context are l10n (localization) and i18n (internationalization).
This app is translated via the GNOME translation system called Damned Lies.
When reporting an issue or suggesting a feature, it can be helpful to base the report on the latest version of the app. To this end, you can check the installation methods below.
If you found an issue or want to propose a change you should try to make sure you have tried out the latest version of Boxes. You can check the current version in the app’s “About” section.
The latest released version on Flathub is version 45.0.
This app allows to install a version of its current development status. Such installations were traditionally generated each night, giving them the name “nightly builds.” Nowadays, they are usually regenerated whenever the main development version changes.
Warning: Nightly builds of apps should only be used for testing and not for actual tasks. You can identify nightly builds of the app on your system via the stripes in the app’s icon and the stripes in the app’s headerbar. They usually use a different configuration than other installations of this app. However, there is no guarantee that the installation of these apps will work as intended. Never work on data with nightly builds of apps without having backups available.
$ flatpak install gnome-nightly org.gnome.BoxesDevel $ flatpak run org.gnome.BoxesDevel
Catching issues and regressions before they land in a stable release is very valuable for a project. You can help with this by trying out an upcoming release. You can do this by trying out the nightly build of the app.
For many apps, the issue tracker is a central place for coordination of app development. It is not only used to track all existing problems but also to plan new features and other miscellaneous tasks.
Reporting issues you found when using the app can be of high value for app maintainers. However, processing issue reports can also take considerable amount of time. You can take on some of the work by trying the following steps:
Search the issue tracker to find out if the issue has already been reported.
Check if the issue also exists in the latest version of the app.
If applicable, try to find out and which exact circumstances the problem occurs.
Report all potentially relevant information, like the version of the app that expose the behavior.
Tracking down the exact cause of an issue can be a very important task. Especially for issues tagged with labels like “Needs Diagnosis” or “Needs Information.” If you can reproduce, that is, trigger the reported problem yourself, you can try to dig deeper. This can go from finding out under which exact conditions the issue appears, over running the app with debug output enabled, to adding debug outputs to the code that narrow down the problem.
Most apps handle feature requests via the issue tracker as well. Note that implementing features and maintaining them as part of the codebase in the future can require a significant amount of additional work. Therefore, you should consider whether a new feature could even be relevant enough to be part of this app.
When suggesting a new feature, it is helpful to focus on the question of what practical problem the feature should solve. Not on how the app should solve the problem or how exactly an implementation would look like. Preferably, you can also give a practical example where you needed the feature.
The issue tracker can also help you find open tasks you could tackle. Before implementing a new feature, it is usually a good idea to check in with the maintainers if merge requests for this feature would be accepted.
This app also has tasks which are labeled with the “Newcomer” tag. Those tasks usually require less prior knowledge or are less complex.
Whether you want to fix a typo, change the user interface, or work on the code of the app, the following information can help you get started. The first step will be to get the app built on your computer, allowing you to play around with your changes. Afterward, you can check the provided documentation on how to get respective tasks done. The subsequent section will show you how to submit your changes.
If you are planning a somewhat larger change or addition to the app, it is often a good idea to check in with the maintainers of the app to find out if that change would be accepted. For this, you should first convince yourself that you can tackle the task at hand by doing the very first implementation steps and then check in with the maintainers via the issue tracker. This is also a good way to check if the project has an active maintainer who can accept your contribution. Despite our best efforts, not all projects are always continuously maintained.
Note that while many community members are happy to help you out when you are stuck, maintainers oftentimes might not have the resources to guide you through a contribution.
If you are overwhelmed by working on an existing GNOME app, you can also look into building your own app for learning purposes first.
When making changes to an app you will usually want to build and test the app with its changes on your computer. For most apps this process can be simplified a lot by using the Builder app.
After starting Builder, you can choose to clone a project. This will download the app to your computer.
You have to enter the repository location. The correct URL can be copied from below.
Depending on your internet connection and the size of the project, cloning the project might take a while. After Builder has completed this step, the project window should open. You might have to confirm the installation of some required dependencies. To try if you can successfully build and start the app, you can now press the “Run Project” button.
If everything goes right, the app should be built. After the build has been completed, the built app should start automatically.
This app is built with the Vala programming language.
After making changes to a project, you can submit them for review. Our goal is to create what’s called merge request or pull requests. That means suggesting a change to a project’s code and data.
We begin with some preparations on GNOME GitLab, where the project is hosted. This process might look quite involved if you are going through it for the first time, but you will become much more accustomed to it over time.
The first step is to create a new GNOME GitLab account if you don’t own one already. You just have to use the linked webform for that.
Next, we want that git on your computer can also use your GNOME GitLab account. For this, you need an SSH key. If you don't have an SSH key yet you can generate a new one using Console. Alternatively, you can generate one using the Password and Keys app.
You now have to add your public SSH key to the “SSH Keys” setting on GNOME GitLab. Public SSH keys are stored in the
.ssh folder in your home directory as files with the ending
.pub. You can print all your public SSH keys via the command
cat ~/.ssh/*.pub. You can also view the public SSH keys using the Password and Keys app.
To suggest changes to a project, you first have to create your own copy of the project on GNOME GitLab. Creating this copy is also referred to as forking. You will need your own copy – or fork – of the project to upload your changes to this copy.
First, you can fork Boxes via the GNOME GitLab page. You only need to do this once for every project you work on.
Now, we have to let git in your local project know of your personal copy on GNOME GitLab via this URL. For this we need to go back to the command line. First, you have to change (
cd) into the project you have been working on. Afterwards you can use the command
$ git remote add my-copy <ssh-fork-url>
<ssh-fork-url> has to be replaced with the SSH URL you looked up in the previous step.
We now arrive at what are more regular tasks when working with git.
First, we want to switch to what’s called a different branch. Branches are variants of the original code where you can, for example, develop a feature, until it is ready to go into the actually used code. To do this you can call
$ git checkout -b my-changes
my-changes is a short description of what you are working on, without spaces.
Next, we want to save the changes you made with git. That’s usually referred to as creating a commit. You can do this with the command
$ git commit -am "Commit Message"
The commit messages should describe your changes. You can learn more about choosing a fitting commit message.
Now, we have to get your saved changes onto GitLab. Luckily, we have already done all the setup with using
git remote add in the previous section. All that’s left to do is now to call
$ git push my-copy
We are finally at the last step. If you check the output in Console after our previous
git push command, you will probably already see a website link showing you the way to create a pull or merge request. You can open it by pressing the Ctrl key while clicking on it. All that is left is to follow the website to finalize submitting your changes.