Documentation for Contributors to Vala
Vala follows a collaborative, open source development model. The following guidelines are here to help if you want to contribute back to the project.
Submitting Bug Reports
Vala uses GNOME's GitLab to track issues.
If you are not a GNOME developer then you will need to first create a fork of Vala to your personal GNOME GitLab instance, which you then clone to your local machine.
Patches to the compiler should include one or more test cases.
Patches will also be accepted as attachments to an issue.
Reviewing and Updating Patches
If your merge request requires updating after review then use git rebase --interactive to squash the changes and git push --force the updated branch to your GNOME GitLab instance. GitLab will then pick up the changes and show them in the merge request.
The Vala repository carries a number of bindings to libraries. The bindings are written in one of three ways:
Generated using vapigen from a GIR (GObject Introspection Repository) file
Generated using vapigen from a deprecated GIDL file
To update a binding the first thing to do is find how the binding is written. Look at the top of the VAPI file. If there is no comment generated by vapigen, do not modify then the VAPI is written manually. For example glib-2.0.vapi is written manually. If the VAPI is generated using files from the ./metadata/ directory then the VAPI is generated from a GIR file. For example gio-2.0.vapi is generated from a GIR file. If the VAPI is generated using files from the ./packages/ directory then the VAPI is generated from a GIDL file. For example the gtk+-2.0.vapi is generated from a GIDL file, but the gtk+-3.0.vapi is generated from the GIR.
Patches should be submitted through the merge request process outlined above. Patches for generated bindings should also include the changes to the VAPI itself. The Vala repository keeps the generated VAPIs in version control as well as the metadata. There is no need for test cases to be added for bindings.
Writing a VAPI Without Using GObject Introspection - detailed guide on writing a VAPI manually
Generating a VAPI with GObject Introspection - details on generating a VAPI using vapigen
Developing the Compiler
The internal API documentation, in Valadoc form, should be built from the source:
make -C doc internal-api-docs
This will generate output similar to https://gnome.pages.gitlab.gnome.org/vala/docs/index.html
Using --enable-coverage will include debugging symbols in the Vala compiler:
make distclean ./autogen.sh --enable-coverage
This will enable Vala source files with line numbers to be shown when using gdb to generate a backtrace after a segmentation fault.
You can also change GLib criticals and warnings to generate a segmentation fault to enable a backtrace. This is done with the G_DEBUG environment variable:
G_DEBUG=fatal-criticals gdb --args my_valac_version my_test_program.vala
See Running and debugging GLib Applications for more information on G_DEBUG.
The Build Server
Vala maintainers make use of a Buildbot server to build a selection of projects written in Vala with a version of Vala from the main GNOME git repository. Of main interest to contributors is the vala-staging builder and also the vala-master builder. Builds from these servers include log files from STDIO for each build. This helps identify any problems with a patch that was committed to Vala.