From b880baee3f6cade78772877bd0ed5a770abed88a Mon Sep 17 00:00:00 2001 From: Max Gaukler Date: Mon, 9 Jun 2025 19:13:50 +0200 Subject: [PATCH] Extend developer documentation Merge in more parts from https://inkscape.org/develop/getting-started , especially about how to contribute (forking, MR). The merge is not finished yet, but this should be a good step forward towards getting rid of the above website and instead redirecting it to the documentation in the Repo. --- CONTRIBUTING.md | 173 ++++++++++++++++++++++++++++++++++-------- doc/building/linux.md | 2 +- doc/readme.md | 7 ++ 3 files changed, 149 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d4f220ea6..5bfcb9680c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ [Inkscape Developer Documentation](doc/readme.md) / -Contributing to Inkscape -======================== +Contributing to Inkscape - Getting started with Inkscape Development +==================================================================== Inkscape welcomes your contributions to make it an even better drawing program for the Open Source community. @@ -11,7 +11,15 @@ You can help improve Inkscape with and without programming knowledge. We need bo As a **non-programmer**, you can e.g. help with support, testing, documentation, translations or outreach. Please see our [Contributing page](https://inkscape.org/contribute/). -If you want to help as a **programmer**, then please follow the rest of this page. +If you want to help as a **programmer**, then please follow the rest of this page. We suggest the following steps: + +1. Know how to contact us +2. Get the source code +3. Compile and run +4. Look at the developer documentation +5. Set up a GitLab account +6. Make changes +7. Submit as Merge Request Contact ------- @@ -26,36 +34,134 @@ Feel free to reach out to us. - Video conference: We regularly meet by video. Please ask in the chat for details. - Real life: About once a year there is an Inkscape summit. We also take part in events like Libre Graphics Meeting. This is announced in the chat and mailing list. -Git Access ----------- -Inkscape is currently developed on Git, with the code hosted on GitLab. - * https://gitlab.com/inkscape/inkscape +Source Code +----------- -We give write access out to people with proven interest in helping develop -the codebase. Proving your interest is straightforward: Make two -contributions and request access. +Inkscape uses the Git version control system, with the code hosted on GitLab. + + * Inkscape core: https://gitlab.com/inkscape/inkscape + * Further tools and parts: https://gitlab.com/inkscape/ + +How to get the sourcode is described in the next step. + +Get the Source, Compile and Install +----------------------------------- + +[Compile Inkscape from source](doc/building/readme.md). + +(If you only want to run Inkscape, but not modify the code, you can also [download a prebuilt Inkscape version](INSTALL.md).) + + +Developer Documentation +----------------------- + +This page is part of the [Inkscape Developer Documentation](doc/readme.md). Here you should find everything you need for programming Inkscape. If not, please contact us or submit a merge request for improvement. + + +Setting up a GitLab account +--------------------------- + +To report bugs and submit changes, you need an account for GitLab. This is free. [Sign up on gitlab.com](https://gitlab.com/users/sign_up). You can find more information in the [Gitlab user tutorial](https://docs.gitlab.com/ee/user/profile/account/create_accounts.html). + + +Submitting Improvements +----------------------- -Compiling and Installing ------------------------- +Changes to Inkscape can be submitted as merge requests on GitLab. If you know how to use GitLab, you can skip this section, *except* for the part about "Changes to CI settings". -See [INSTALL.md](INSTALL.md). +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. Feel free to ask in the chat and look at [GitLab's tutorials](https://docs.gitlab.com/tutorials/learn_git/). -Patch Decisions ---------------- +### Workflow + +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. Our motto for changes to the codebase is "Patch first, ask questions later". When someone has an idea, rather than endlessly debating it, we encourage folks to go ahead and code something up (even prototypish). + You would make this change in your own fork of Inkscape (see GitLab docs about how to fork the repository), in a development branch of the code, which can be -submitted to GitLab as a merge request. Once in an MR it is convenient for other +submitted to GitLab as a merge request (MR). Once in an MR it is convenient for other folks to try out, poke and prod, and tinker with. We figure, the best way to see if an idea fits is to try it on for size. -So if you have an idea, go ahead and fork Inkscape and submit a merge request! -That will also take care of running build tests on the branch, although we would -encourage you to check if everything builds and tests pass on your system first. + +So if you have an idea, go ahead: + +### 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. + +Fork the inkscape project (https://gitlab.com/inkscape/inkscape): Create a fork by clicking the Fork icon in the upper right corner of [Inkscape's main GitLab page](https://gitlab.com/inkscape/inkscape). See the [GitLab documentation](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork) 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. + +### 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. + +**Important**: +Go to your fork > Settings > CI/CD > General Pipelines > Timeout. Change the Pipeline Timeout to `3 hours`. If you can not find the setting, check the [GitLab documentation](https://docs.gitlab.com/ci/pipelines/settings/#set-a-limit-for-how-long-jobs-can-run). + +### Creating a branch + +Merge requests operate on branches, so it necessary to create a new branch for the changes you want to contribute. Use a separate branch for each bug/feature you want to work on. 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 checkout -b fix-for-bug-xyz +``` +on the local clone of your fork. Make your changes (the bugfix) and commit them. + +Find more information in the [GitLab documentation](https://docs.gitlab.com/topics/git/branch/). + +### Commiting changes + +Make the changes and `git commit` them. + +See the [Commit Style](#commit-style) for how to write good commit messages. + +### 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 fork repository will make it publicly available. + +To push the branch to your fork of Inkscape on GitLab, run + +``` +git push origin fix-for-bug-xyz +``` + +This 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-xyz +``` + +with 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 pictures or 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. + +Try to keep your MR current instead of creating a new one. You can always push new changes to your branch to update the existing MR. + +Rebase your MR sometimes. + + +### Merge request review + +Merge requests are reviewed. Other developers will look at your MR and give feedback. Please check regularly if there were new comments on your MR. + +Once everyone is happy, the MR is approved. + +Repository access +----------------- + +Any change (MR) to Inkscape must be approved by at least one other person with write access. +We give write access out to people with proven interest in helping develop +the codebase. Proving your interest is straightforward: Make two +contributions and request access. Coding Style ------------ @@ -65,6 +171,15 @@ on the style to use for code. If reading style guidelines doesn't interest you, just follow the general style of the surrounding code, so that it is at least consistent. +Before making big changes, we recommend to discuss your idea with us. Someone else might already have plans you can build upon and we will try to guide you! + +Commit Style +------------ + +Write informative commit messages ([check this](https://chris.beams.io/posts/git-commit/)). + +Use the full URL of the bug (`https://gitlab.com/inkscape/inkscape/-/issues/1234`) instead of mentioning just the number in messages and discussions. + Documentation ------------- @@ -72,6 +187,13 @@ Code needs to be documented. Future Inkscape developers will really appreciate this. New files should have one or two lines describing the purpose of the code inside the file. +Debugging +--------- + +Inkscape can be debugged with `gdb`. This works best with a debug build, for which you add `-DCMAKE_BUILD_TYPE=Debug` to the CMake arguments (see [Compiling Inkscape](doc/building/readme.md)). + +To diagnose memory access issues, building with the Address Sanitizer `-DWITH_ASAN=ON` is recommended. Note that this will slow down inkscape by about 3x. + Profiling --------- @@ -124,16 +246,3 @@ Submodules / Errors with missing folders Make sure you got the submodules code when fetching the code (either by using `--recurse-submodules` on the git clone command or by running `git submodule init && git submodule update --recursive`) - -General Guidelines for developers ----------------------------------- - -* If you are new, fork the inkscape project (https://gitlab.com/inkscape/inkscape) and create a new branch for each bug/feature you want to work on. Try to Set the CI time to a high value like 2 hour (Go to your fork > Settings > CI/CD > General Pipelines > Timeout) -* Merge requests (MR) are mandatory for all contributions, even the smallest ones. This helps other developers review the code you've written and check for the mistakes that may have slipped by you. -* Before working on anything big, be sure to discuss your idea with us ([IRC](irc://irc.freenode.org/#inkscape) or [RocketChat](https://chat.inkscape.org/)). Someone else might already have plans you can build upon and we will try to guide you ! -* Adopt the coding style (indentation, bracket placement, reference/pointer placement, variable naming etc. - developer's common sense required!) of existing source so that your changes and code doesn't stand out/feel foreign. -* Carefully explain your ideas and the changes you've made along with their importance in the MR. Feel free to use pictures ! -* Check the "Allow commits from members who can merge to this target branch" option while submitting the MR. -* Write informative commit messages ([check this](https://chris.beams.io/posts/git-commit/)). Use full url of bug instead of mentioning just the number in messages and discussions. -* Try to keep your MR current instead of creating a new one. Rebase your MR sometimes. -* Inkscape has contributors/developers from across the globe. Some may be unavailable at times but be patient and we will try our best to help you. We are glad to have you! diff --git a/doc/building/linux.md b/doc/building/linux.md index 6198ece34c..2e418553e1 100644 --- a/doc/building/linux.md +++ b/doc/building/linux.md @@ -65,4 +65,4 @@ To compile again after making changes, you can re-run the `ninja install` comman ## See also - [Contributing and Developing](../../CONTRIBUTING.md) - [Advanced Information on Compiling Inkscape](doc/build/general_advanced.md) -- [Packaging for Ubuntu Snap)](../snap/README.md) +- [Packaging for Ubuntu Snap](../../snap/README.md) diff --git a/doc/readme.md b/doc/readme.md index 224523b24e..17f4922489 100644 --- a/doc/readme.md +++ b/doc/readme.md @@ -7,6 +7,13 @@ For user-facing documentation, please refer to the [Inkscape website](https://in - [Installing](../INSTALL.md) - [Contributing and Developing](../CONTRIBUTING.md) + - [Compiling Inkscape](./building/readme.md) - [Style guide for developer documentation](./documentation_style.md) - [Developing Inkscape with Visual Studio Code on Windows](./vscode/readme.md) + + + +Some short-lived or historical content can be found in the [Inkscape wiki](https://wiki.inkscape.org/). + +TODO: We are currently working on moving content all relevant long-lived developer documentation from the Wiki to here in the Git repository. -- GitLab