Hacking:Developer FAQ

How can I support Valentina development?
By using Valentina and reporting any bugs you find to Issue Tracker you're helping a great deal. But there are other non-technical ways of supporting the development of The Valentina as well.

Valentina has an user manual that you can help us improve and translate. Also we need your help with localization.

You can also have a look at bug reports filed for Valentina and pick something. You can use the issue tracker to find bug reports you could take care of, but we encourage you contacting us beforehand to find out if the task you picked is still valid. It's best to discuss working on something in either mailing list or IRC channel before beginning to fix things and implement features. This is because requests have to be checked against bigger design decisions. We'd hate if you wasted your time on something that shouldn't have been done.

Major planned changes are listed at the feature roadmap page.

Contacting the team is essential when starting to solve bugs or realizing enhancements/features.

What should I know when starting with open source development?
If you're new to open source development, the article '10 golden rules for starting with open source' from Tobias Schlitt offers useful and worth knowing hints.

Who is planning Valentina's development?
Valentina team does not have time-based schedules, instead we rely on a feature roadmap.

We use Mercurial named branches for developing major new features. Each new feature lives in own feature branch. If a feature is ready for inclusion into the main develop branch, it is merged. The decision, whether it's ready, is made by the core team (currently: Roman).

How can I become a Valentina developer?
If you are a developer who wants to start contributing code to the Valentina, the best way to get to know its structure is by fixing bugs reported in Issue tracker. Pick a bug, perhaps ask the advice of another developer as to whether he/she thinks it will be an easy bug or not, and then fix it. Sounds easy, doesn't it?

After helping with a couple of bugs, people will start to recognize your immense talent, and you will be on your way to becoming a Valentina developer. Any time you feel able, you can pick a smaller enhancement request and have a go at implementing it. It's that easy.

Where should I go for help when I need it?
There are several channels of communication:
 * Main mail list (recommended way).
 * IRC channel #valentina. Abandoned right now.
 * You can ask question on Facebook.

Where can I find documentation for the Valentina API?
There are several ways, see Hacking:API documentation.

What is the best way to submit my changes?
The best way to submit your changes is to make a fork, push your changes to your fork and than make a pull request. See Hacking:Making pull requests.

You can also send it to the mailing list, but this way will works well only for small patches. For big one you will mostly asked to make a pull request.

What is the preferred coding style used in Valentina?
See our Hacking:Code style conventions.

How can I configure my editor for this coding style?
Your editor will not be able to do everything for you, but you can configure most editors so that they use two spaces for indentation, use spaces instead of tabs, etc.

If you are using Qt Creator go to Tools -> Options... -> C++ -> Code Style. Then import code style file from /share/valentina_code_style.xml. If you are using another editor and you know how to configure it correctly, please tell us about it or update this page yourself.

How can I automate inserting copyright header?
Because each a source file should contain a copyright header. We will not merge you changes without such a header.

If you are using Qt Creator take the file from /share/copyright_template.txt, edit the author field and save somewhere you have access. Then go to Tools -> Options... -> C++ -> File Naming and select path to the file.

If you are using another editor and you know how to configure it correctly, please tell us about it or update this page yourself.

Who coordinates the Valentina translation efforts?
Any help with translations is appreciated. If you want to help, please register on Transifex and make a request to join Valentina translation team.

More information about Valentina and localisation can be found in the page Hacking::Localization.

Where do I find the code?
You can find the Valentina source code hosted on bitbucket.

If you seek last unstable version look at the develop branch. It contains source code for a next major release (for example 0.5.0).

The release branch is place for bugfixes for previous major release (0.4.1, 0.4.2 ans so on) or feature freeze state depend on developing state.

The default branch only for releases. This is the best place if you are looking last stable release.

Compiling Valentina

 * General: Hacking:Building
 * Descriptions for Linux: Hacking:Building/Linux
 * Descriptions for Windows: Hacking:Building/Windows

What are planned deadlines for next edititons of Valentina? Are there any?
Once we have a bigger team, we probably will have deadlines. At this point we don't have the resources to plan time-based releases.

I see compiler warnings. What should i do?
Try to fix them all. Even if you think they are wrong. Waring is not an error, but shows dangerous places in code.

What is Issue Tracker?
The Valentina project uses issue tracker provided by bitbucket for tracking of bug reports, enhancement requests etc. Read more about why we use issue tracker for bugs.

A beginners tutorial describing how to report a bug can be found in the Hacking:How To Report Valentina Bugs document.

What is the meaning of the WONTFIX status code in Issue Tracker?
If the status of a bug is changed to WONTFIX it means the Valentina developers need more information from the bug reporter in order to resolve the bug.

What is the best way to refer to a bug in Issue Tracker?
The best way to refer to a bug is “#nnnnn”, where nnnnn is the bug number.

What is the proper way of handling duplicate bug reports?
A bug report describing the same bug as a previous bug report should be marked as DUPLICATE of the older one. In some exceptional cases, it is possible to mark an old bug report as DUPLICATE of a newer one (e.g., when the newer bug report has a significantly better description than the older one).

Another exception is when the same person submits the same bug report several times (same description): in this case, it is better to mark the additional copies of the bug report as INVALID in order to avoid inflating the statistics about the number of duplicates.

What is the proper way of marking a bug as RESOLVED?
When fixing a bug, always mention the bug number (#nnnnn) in the commit message. For example, "Resolved issue #345". once the changes are in mercurial, bitbucket will automatically mark an issue resolved/fixed depend on word you used.

Don't forget with your code changes additional add string about fix to ChangeLog.txt file.

Mercurial
We recommand you to read Mercurial: The Definitive Guide

How do I commit to the Mercurial tree?
Valentina uses bitbuket's Mercurial repository for source code storage. Please read their guidelines.

Please note that we want to work with you for a while before we can confirm that you are going to make a great upstream developer. Until then you can maintain your own fork on Bitbucket.

What should I put in the commit message when doing a mercurial commit?
Please put a short explanation of the change on the first line. Usually it contains words Fixed/Resolved issue, number of bug with symbol '#' and title of bug from the issue tracker.

Example: Fixed issue #333. Title of bug.

Then, after an empty line, you can describe the change in more detail using as many lines as you need. Try not to exceed 72 colums.

Do i need to add summary of my commit to a bug report?
No, if you did all right the Bitbucket will do all automatically for you.

Where can I learn more about the Qt framework system used by Valentina?
You can start with Qt Documentation

What is openhub.net for? Why developers are listed there and not on an official Valentina website?
The Valentina project itself doesn't maintain a site with an overview of the developers. If you want to know who are most active developers in the project, you can look at openhub.net statistics of the last 12 months. Openhub.net is free, public directory, a web service and online community platform that aims to map the landscape of open source development (see the description in the English Wikipedia). It collects information from public available source code repositories and creates statistics from it. To read more about openhub.net, visit the openhub.net self-introduction.

Is there a Valentina user FAQ available?
Yes, you find it here.