Extending the "Getting Started with Inkscape Development" Guide
I've recently run into the problem of the too short default CI/CD timeout setting of GitLab and missing the Allow commits from members who can merge to the target branch. checkbox on creating a merge request.
As suggested by the discussion on the inkscape-devel mailing list, I've come up with a text proposal that could be added to the "Getting Started with Inkscape Development" Guide in the Inkscape homepage. It is not intended as an in-depth guide, because numerous detailed resources regarding these topics can be found on the web but rather as a "you may need to know and look this up" pointer. The text starts below the horizontal line. There are also two comments marking topics where I am not sure.
Note: The text has been edited. See the history recorded by GitLab for older versions related to the discussion.
Contributing Code
The above instructions show how to obtain Inkscape's source code and compile it. If you just want to look around or make some changes for your personal use only, this is a good starting point.
Once you have implemented new features or fixed bugs, you may want to contribute the changes back to the official Inkscape source code, such that other people can also benefit from your efforts. To do so, the recommended method is to send a merge request on GitLab so that developers can submit feedback on your changes.
The following sections are a rough guide to introduce you to the topic. They should get you started, but are no in-depth guide and provide only some indications of the required steps. If you are new to Git you will likely need to lookup some of the commands and terms on your own.
Creating a fork
A fork is your own copy of a GitLab repository on GitLab. Contrary to the official repository of Inkscape, you can push changes to your fork (you have write access) and thereby make them publicly available.
Create a fork by clicking the Fork icon in the upper right corner of Inkscape's main GitLab page. See the GitLab documentation on this topic for more information. You then work with your fork instead of the official repository, i.e. clone it to your local storage.
To keep your fork up to date with changes in the official Inkscape codebase you can enable the mirroring functionality of GitLab. Otherwise you won't see changes in the official codebase performed by other developers in your fork unless you update it manually.
Note: The mirroring functionality only transfers changes from the official Inkscape repository to your fork on GitLab. To update your local copy, you still have to run git pull to obtain the changes from GitLab.
Changes to CI settings
When you push changes, automatic builds and tests on the GitLab servers are initiated. The default timeout of GitLab is too short for the Inkscape build. See the GitLab documentation where to find it and change it to 3h.
Creating a branch
Merge requests operate on branches, so it necessary to create a new branch for the changes you want to contribute. Assume you are going to fix a nasty bug. Create a branch with an appropriate name, e.g., fix-for-bug-xyz, by running
git -b fix-for-bug-xyzon the local clone of your fork. Make your changes (the bugfix) and commit them.
Pushing changes
When you are done with your changes, it is usually a good idea to take a few moments and review the status of your local Git repository and your work to make sure everything is the way you want. Pushing the branch to your GitLab repository will make it publicly available.
To push the branch to your fork of Inkscape on GitLab, run
git push origin fix-for-bug-xyzThis also produces a notification like
remote: To create a merge request for fix-for-bug-xyz, visit:
remote: https://gitlab.com/userxxx/inkscape/-/merge_requests/new?merge_request%5Bsource_branch%5D=fix-for-bug-xyzwith a link for creating a merge request (where userxxx is your username). This message is only output for newly created branches.
Creating a merge request
There are multiple ways to create a merge request. For example, you can use the above link printed by git push to create a merge request. Alternatively, you can select your branch on the GitLab web interface and click Create merge request in the upper right corner. See the GitLab documentation for more information on creating merge requests.
In GitLab's merge request form, enter a title, a meaningful description and attach files if appropriate.
It is recommended to tick the Allow commits from members who can merge to the target branch. checkbox. This allows the core developers to push changes directly to your branch and thereby simplifies the integration of your code into Inkscape.