Clairvoyant
Ask questions, get psychic answers
Ask questions, get psychic answers
On this page you can learn how to contribute to Clairvoyant. 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).
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 Clairvoyant. You can check the current version in the app’s “About” section.
The latest released version on Flathub is version 3.1.10.
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 manually building the app and trying it out.
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 under 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.
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.
For getting started with the Vala language, we recommend the Vala Tutorial or the Beginners Tutorial, which also covers Vala. You can find other important resources below.
</div>
<div>
<b>Vala Bindings API References</b>
How to use GTK, the underlying library for user interfaces, and other libraries
</div>
</div>
<div>
<b>Development Platform</b>
Main development repository of the Vala language and compiler, issue tracker and contribution platform
</div>
After making changes to a project, you can submit them for review. Our goal is to create what’s called a merge request or pull request. That means suggesting a change to a project’s code and data.
We begin with some preparations on GitHub, 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 GitHub 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 GitHub 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 Passwords and Keys app.
You now have to add your public SSH key to the “SSH Keys” setting on GitHub. 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 Passwords and Keys app.
To suggest changes to a project, you first have to create your own copy of the project on GitHub. 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 Clairvoyant via the GitHub 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 GitHub 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>
where <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
where 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.