Tips and tricks for beginner developers
This is a list of tips and tricks for developers who are new to Stellarium. It's intended audience is mostly people who wish to make a contribution larger than a simple patch - interface tweaks, new features, new plug-ins, alternative GUIs and ports to other platforms, etc.
The level of usefulness and knowledge required by this information varies, but most of this stuff is very basic.
If you want to work on something and you would like to have your work integrated into Stellarium, please let us know before you start, preferably using the mailing list. We can tell you if your idea is worth pursuing and we may suggest ways to implement it.
Stellarium uses Bazaar for version control. It's a good idea to get some basic grasp of Bazaar and its concepts before starting work. It comes with built-in documentation, but the online documentation is more friendly to new users.
- You can use Bazaar either from the command line, or from the Bazaar Explorer GUI. Ironically, sometimes the command line is more convenient than the GUI.
- The standard workflow for large outside (and inside) contributions is "feature branches":
- You pull a local copy of the trunk branch (lp:stellarium).
- You push it to personal branch on Launchpad (for example, lp:~your-user-name/stellarium/branch-name); this will make it show up on the branch list. Each branch gets its page, which is publicly visible by default, you can edit its properties and description from Launchpad's web interface - see Launchpad's documentation for details.
- You work on the local branch, committing changes and then pushing them to the remote branch on Launchpad.
- After you are done working, you propose the branch for merging in the trunk branch using Launchpad's web interface (use the "propose for merging" link on the branch's page).
- Some of the core developers review(s) the changes and approve or disapprove of the merge.
- Please, use separate branches for separate lines of work - if you are working on a FlyingPigs plug-in and a feature that displays distance to the planets in cubits, do not put them into the same branch. Keeping work on different features in separate branches makes code review and testing easier.
- Make sure you add your build directory to Bazaar's ignore list, otherwise you risk committing all the temporary build files to the branch. We will refuse merging branches with this kind of thing in the commit history, so revert/uncommit while it's still possible. (Bazaar Explorer is better than the command line here, because it displays very prominently all the files added to version control after the last commit, and it's easy to catch errors.)
- You will probably find yourself using at least two local branches: the trunk branch and one or more feature branches. In such cases, it makes sense to use a "shared repository" (see Bazaar's documentation) to avoid having to download the whole branch history every time you create a new feature branch.
- Bazaar Explorer will ask you if you want to create a shared repository when the first time you pull a branch. Be careful with the choices you make in the dialog windows. :)
- The directory structure typically looks like this:
../stellarium/ // shared repostiory ../trunk/ // local copy of the trunk branch ../branch-1/ // local copy of a feature branch (FlyingPigs?) ../branch-2/ // local copy of another feature branch (distance in cubits?) etc, etc.
Stellarium's source code has been documented with Doxygen. A Doxygen project file with the appropriate parameters is generated at compile time in the build directory. This is the way we create Stellarium's online developers' documentation. Because the online documentation is rarely updated (typically, slightly more often than once per release), you'd better run Doxygen on your copy of the trunk branch every time you update it.
In addition to API documentation, it also includes separate pages about the general structure of the code, coding style, file structure, scripting, plug-in programming, etc. At the very least, you should become familiar with the coding style conventions.
And remember The Mantra:
- Read the documentation.
- Keep the documentation up-to-date.
- Document new code.
- Read the documentation! This is one of the first things you should do before starting work, especially if you are working on the GUI.
- Be aware of the way the documentation is structured: the page for each class lists only the members of that class, and not of its parent classes - and many Qt classes have a lot of parents. So it's possible to miss useful signals, slots, etc. if you don't read the parents' documentation too.
- Ignoring the parent documentation is the cause of a few newbie errors.
- Using Qt Creator is strongly recommended. It has integrated documentation and auto-complete for Qt, as well as many other useful functions (such as recognising vim commands).
- Qt Creator can import Stellarium's coding style settings from a file, which is an easy way to make sure that you won't mix tabs and spaces and drive everyone else nuts. :)
- You can easily start small new Qt applications to "sandbox" ideas.