Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The fastest way to get a collection of common app dependencies and developer tools is to install elementary-sdk
from Terminal:
You can quickly install all known dependencies for a project with build-dep
:
This installs the dependencies for the currently-released version, so it may miss dependencies for unreleased updates. In those cases, refer to the project's README.
To make it easier to follow the elementary Code-Style guidelines you can use vala-lint.
The GTK Inspector is similar to a web browser's inspector, but for GTK apps. Using the Inspector can greatly speed up development, and allows you view and to test out changing properties without recompiling an app. You can also test out temporary in-app CSS.
First, make sure you have elementary-sdk
installed. Then enable the Inspector keybinding:
Focus an app, then launch the Inspector by pressing Ctrl+Shift+I to inspect the widget beneath your cursor, or Ctrl+Shift+D to open the inspector without a widget selected.
You can also run it temporarily together with an app by running:
You can audit your system for files that have been changed from their originally installed packages:
View changed files:
View which packages those files belong to:
Assuming that you've used --prefix=/usr
when installing custom version you can restore them using:
Gala is the window manager of elementary OS. If it crashes or freezes during development, it can be nonobvious how to recover. Here's how to do it:
Go to one of the virtual consoles by pressing: Ctrl+Alt+F1
Log in
If Gala didn't crash but froze, you can kill it by running killall gala
Restart Gala by running DISPLAY=:0 gala --replace &
Switch back to the graphical session by pressing Ctrl+Alt+F7
If Gala doesn't start, you can reinstall the latest stable version by running sudo apt install --reinstall gala
.
Localizing our website and apps is an important part of making elementary OS available to as many people as possible. Instead of relying solely on an internal translation team, we use crowdsourcing so that anyone can submit translations with little to no technical knowledge. In order to keep our voice consistent across the entire platform, and to help new translators get started, we’ve put together this translation guide.
Our apps and website are translated through Weblate: A libre web-based translation management system. In order to submit translations, you should:
Have a Weblate account
Set your language preferences
Browse our translatable projects
Once you’ve selected a project, you can provide suggestions for strings that have not yet been translated, or suggest changes to strings that have already been translated. These suggestions will be evaluated by a translation team member and they will choose the most appropriate one. For more information about Weblate, you can refer to its documentation.
By default, you will only be able to suggest translations. If you would like permission to save translations directly, join us on Matrix and message an admin your Weblate username and the language you want to translate.
When translating you may encounter a situation where you have to decide between several ways of saying the same thing. In these situations we refer to the Ubuntu general translator guide, and for language specific issues, we follow Ubuntu's team translation guidelines. Following these guidelines ensures uniform translations, while also allowing anyone to contribute.
If you don't want to translate using Weblate, or want to make a lot a changes at once, you can also translate offline. To do so:
Go to a project you want to translate
Choose your language
Click on "Files" and then select "Download translation as gettext PO"
Choose your favorite text-, code- or PO-editor (e.g. Poedit)
Start translating
Once you've finished, use the "Upload translation" option in the "Files" menu on the same page you downloaded the po files from
Some projects have been excluded from translations for technical or logistic reasons.
Developer and contributor facing documentation is excluded since developers and contributors will need to be able to read and write in English to do their work.
The elementary store is excluded since product information is only stored in English on the Printful platform, so it cannot be translated.
Tips for getting your pull requests reviewed
Your PR description should make it easy for a reviewer to know what they are reviewing before they see the code. To avoid wordy descriptions, use bulleted lists to describe changes. When appropriate, add a screenshot or a short video that makes your change more obvious. Good descriptions cut time on the time a reviewer needs to invest and makes your PR more attractive.
If it's not obvious, it can also be helpful to include instructions on how to test your PR, including any pre-requisites or dependencies.
When you have your initial version for the proposed change working, look at your changes once again and ask yourself if anything could be improved before marking it "Ready for Review". Be sure to check that:
✅️ Your branch adheres to the elementary code style guide
✅️ No New Terminal warnings are introduced
✅️ Your branch passes required status checks
If you need help or your branch isn't quite ready for review, you can open a Draft pull request and convert it to "Ready for Review" later
The most helpful advice for getting your code reviewed and merged quickly is to keep your diff as small as possible. Small diffs are less intimidating for reviewers, easier to test, easier to read, and have a much smaller chance of regression.
When proposing big changes, breaking up your work into several smaller pull requests is still considered best practice. Consider linking to an issue or discussion that explains the overarching goal.
Proposed changes should generally only implement things that are actually needed right now, not just when you foresee that they may be needed in the future. This is known YAGNI—You aren't gonna need it. Combined with continous refactoring, the YAGNI principle keeps the code base as simple as possible while helping us to avoid technical debt.
It can be tempting to refactor code as you go, but this can make it harder for a reviewer to see what has been changed in your branch. If you need to refactor some code in order to make your change, consider submitting multiple PRs or separate refactoring commits from functional change commits and make it clear that you've done this in your pull request description. This extra step makes it much easier for another person to review your changes and minimizes the risk of regression.
It's possible to clean up your Git history after the fact with Interactive Rebasing.
Naming is one of those things that feels trivial but really helps in a few years when it's all new eyes on some code. It can make it much easier to figure out what's happening if we use names that are self explanatory and not too generic, especially if the names feel similar to those used in platform libraries like GLib and GTK.
Code comments should be used any time it's not immediately clear why something is being done. Comments shouldn't be used to describe obvious changes.
Guidelines to make code reviews fruitful for developers and reviewers alike
Code reviews play a crucial role in the development process. Having other people verify your code not only improves overall code quality, it serves an even bigger purpose: providing an opportunity to learn from each other. This guide aims to lower the barrier to reviewing code by providing a common ground of best practices and philosophies which have proved to be useful over the years.
The roles of developer and reviewer are not mutually exclusive—you can be both. And we highly encourage you to perform both roles, because this leads to more diverse reviews which help us to improve the overall user experience of elementary OS.
You don't need to fully understand the codebase to test its functionality. Often the feedback provided by a partial review helps to keep the momentum and multiple partial reviews eventually lead to a full review.
If there's code you don't understand, ask about what it does. The chances are good it either needs a comment, could be refactored, or you get to learn something new!
Because of Murphy's law ("Anything that can go wrong will go wrong") we want to make extra sure to keep an eye on potential pitfalls during code review. This is especially true for code that is responsible for carrying out a user's intent. Code which fails to execute a user initiated action and is unable to inform the user about the error leads to a bad experience.
If you come across something you like about a proposed change, don't hesitate to let the developer know. Its just more fun to work with people who recognize the effort made.
Everything that we make is 100% open source and developed collaboratively by people from all over the world. Even if you're not a programmer, you can get involved and make a difference.
Looking for documentation on creating your own apps? See Developer Documentation instead.
elementary OS is created and used by people from all around the World; help us make the experience even better by translating it into more languages. Both elementary OS and our website are openly translated using an online platform called Weblate
Our desktop environment and all its apps are built using Vala, Gtk, Granite, and a number of other open libraries. We host all of our code and do all development openly on GitHub.
We release updates every month with new features and bug fixes based on the feedback that is reported to us on GitHub. Report Issues, request features, and start discussions directly with the developers and designers that make elementary OS
Many apps will create logs for various types of errors with additional information that a developer can use to locate the source of the issue. Including those logs in your issue reports when you experience a problem can help solve the problem faster.
To view existing logs from all your applications you can use journalctl
``
By default, debug messages are not shown since they can be quite noisy in normal usage. To see debug logs, start the app from Terminal using the environmental variable G_MESSAGES_DEBUG
If the app in question is a Flatpak app, like the apps available from AppCenter, you'll need to start the app with flatpak run
as well:
Now that logs are being printed to Terminal, reproduce the issue you're experiencing then copy and paste the Terminal output to the bottom of your issue report.
For information on creating logs in your app, see the developer guide
elementary uses GitHub to track issue reports and feature requests publicly. You can send feedback to the team to inform us of a problem you encountered or an improvement that you would like to see.
To get started with issue reporting, open "System Settings" and navigate to the "System" page. Select "Send Feedback", which will open the Feedback app. From here, choose a category that best describes the general area of the issue, and then choose a specific project to open a new issue against. This will open your web browser to the relevent GitHub page where you can view and create new issue reports.
If you can't find a specific project or aren't sure which project to file against, that's okay! Do your best and if the issue report needs to be migrated to a different project, a bug manager will take care of it for you.
You can also see a list of all elementary Github projects on this page and search for projects here. When you've found the project you'd like to open a new report against, open it and then select the "Issues" tab.
When filing a new report, it's a good idea to search the issue list to make sure your report hasn't been filed already. If your report has already been filed by someone else, you should add the 👍️ reaction to the report to indicate that you are also affected.
Only comment on an existing issue report if you can provide additional useful information that may help track down the source of the issue. Do not comment things like "I have this problem too" or "This is a really important issue"
If your report has not already been filed, select the green "New Issue" button at the top right corner of the "Issues" page. Keep in mind the following information while filing your report:
This will be the title of the issue on the issues page. It's important to be specific because it makes it much easier for a developer or bug manager to search the issue list and helps avoid duplicate reports.
❌️ "Performance is bad"
This summary is too vague and could possibly describe a number of different issues.
✅️ "UI is unresponsive while importing"
This summary describes the specific case where we're experiencing a performance issue and what that issue is in a concise way.
Your issue summary should also not include things in brackets like "[bug]" or "[feature request]". elementary uses labels to categorize issue reports.
The most important thing for an issue report is making sure that a developer will be able to understand and reproduce the issue that you're facing. Describe what happened and contrast it with what you expected to happen instead. If necessary, include exact numbered steps to reproduce the issue.
❌️ "Queuing is unintitive. I don't like the way it works"
This description leaves too much room for interpretation and doesn't specifically describe a problem that can be resolved.
✅️ "When I add items to the queue, they appear at the top. I expected them to appear at the bottom instead"
This describes a problem in a way that is actionable and objective and explains how to reproduce the issue.
Include relevant information like your OS version or any modifications you've made to the system (like changing your window manager or kernel). If you're reporting a crash, make sure to include a backtrace.
If your report does not contain enough information for a developer to reproduce the issue, it may be labeled as "Incomplete". If it is, a developer will make a comment requesting additional specific information. If you do not provide that information, your report will eventually be closed since it is unable to be acted upon as filed.
If you're not sure about anything above, you are always welcome to chat with community members and developers in the Community Slack. We might be able to help you track down the project where you should report an issue, or perhaps even aid you with any English language issue you might come across. Most developers want to help you make good bug reports.
elementary uses GitHub Issues both for reporting problems and for tracking feature requests. In addition to what's been mentioned in Reporting Issues, keep in mind the following tips when creating new feature requests:
It's often tempting when creating a feature request to only describe the proposed solution, but don't forget to fully describe the problem that your proposal is meant to solve. Describing the problem is an essential step to ensure that a proposed design meets its goals.
If you're having trouble describing the problem in a concise way or it involves a larger design change rather than a single new feature, consider starting a discussion instead
If you can, include a mockup or a sketch of what your proposed new feature would look like. Or, if there's another project that implements this feature, include screenshots or links to that project.
If there could be alternative solutions to your intial problem, describe them and their merits. A developer may decide that a certain specific feature request is out of scope for a project or conflicts with its other design goals, but if you include alternative solutions one of those may work better and be accepted as a solution.
elementary uses GitHub to not only track issue reports but also for planning improvements and design changes.
If you want to start a larger conversation around a design change that could incorporate many smaller changes or needs some discussion before it can be actionable, you can use GitHub Discussions.
As described in Reporting Issues, you can use the Feedback app to find and open the relevant project page to start a new discussion or you can manually search for projects on GitHub. When you've found what looks like the right project, head over to the "Discussions" tab and select "Ideas" in the sidebar to see design proposals and conversations.
Just like when reporting issues, please search open discussions to see if you could be participating in an already open discussion before creating a new one.
To start a new discussion, select the green "New discussion" button in the top right and keep these tips in mind:
A good design proposal should have clear design goals and often these can be expressed as GitHub issues. Referencing issues that should be considered and solved within the scope of this design discussion helps guide the direction of discussion and gives developers a way to start working towards solutions. Creating new issue reports as part of the design process can also have a few other benefits:
It will make your design proposal less intimidating. A big design proposal can mean a big time investment that will likely have to be taken on by someone volunteering their free time. Smaller changes that can be incorporated over time are more likely to be adopted and resolved
It allows developers to track their progress. Even if a developer wants to implement your entire proposal right away, they might not be able to. Giving them a way to “check off” pieces as they go makes it more likely that a part of your design won’t be forgotten about when it’s translated into code.
It allows developers to scope down your proposal. It's possible that some part of your proposal doesn't fit within the project scope or conflicts with another part of its design. Breaking up your overall proposal into smaller action items increases the change that at least some part of your proposal will be incorporated, even if other parts of it can't be.
Designers are often opinionated and passionate people, but please try to remember that developers are people too. It's important to be objective about the current design of a project, but try to avoid disparaging others' work and keep in mind the Code of Conduct. The outcome of a design discussion should be exciting and inspiring and is an opportunity for collaborative problem solving.
If part of your proposal conflicts with an existing project goal or is considered out of scope, you might have to go back to the drawing board a bit! Developers may provide feedback that means your idea needs to change a little bit before it can be worked on. Designs can often go through many revisions or take some time before everyone is happy and work can begin.
The GNU Project Debugger (gdb) is a general purpose debugger, but we're mostly going to focus on getting useful information when an application crashes. To get started, open an application in gdb, for example AppCenter by running:
Now run this application by typing run
and pressing enter.
If the application doesn't crash right away try reproducing the crash.
Get more information by typing backtrace
and pressing enter.
Please share the lines after (gdb) backtrace
, those should provide useful information.
For more information see the manpages by running: man gdb
. Another tutorial: Debugging with GDB
Running the application under gdb slows down the application and is problematic to reproduce some crashes. In such cases, it is recommended to use the systemd-coredump service which will gather application information on crash.
Let's take our example above of AppCenter: if the application would have crashed without understanding what might have happened, the service would retain the backtrace which is then replayable with:
If there are lines such as 0x00001234deadbeef in ?? ()
it means that we are missing some debugging symbols.
The debugging symbols of elementary OS are hidden by default (as they are taking some space). To be able to discover then, we need to add their corresponding debian source:
We can then install all the missing debugging symbols with:
Rerunning coredumpctl debug
should now show more useful traces.
For a flatpak application, we can use flatpak-coredumpctl io.elementary.elementary.calculator
to see the latest traces of a crash inside flatpak.