diff --git a/images/en/Merge_Request_Label_Workflow.png b/images/en/Merge_Request_Label_Workflow.png new file mode 100644 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@ - Wolthera van Hövell tot Westerflier - Boudewijn Rempt + - Agata Cacko :license: GNU free documentation license 1.3 or later. .. _gitlab : https://invent.kde.org @@ -145,19 +146,185 @@ Forking on Gitlab ~~~~~~~~~~~~~~~~~ -.. note:: +#. Forking on gitlab is done by going to the `repository`_ and pressing :guilabel:`fork`. You will then make a personal fork of the repository. - Work In Progress. + Your fork will probably be located here: + + :: + + https://invent.kde.org//krita -#. Forking on gitlab is done by going to the `repository`_ and pressing :guilabel:`fork`. You will then make a personal fork of the repository. #. In your fork, you press :guilabel:`clone` to get the git urls to do the ``git clone`` from. You can then pull and push your commits from these. - + + .. code-block:: bash + + # for ssh access + git clone git@invent.kde.org:/krita.git + # for https access + git clone https://invent.kde.org//krita.git + You can also use the :guilabel:`Web IDE` to make your changes on invent.kde.org, but because Krita is a cpp program, we don't recommend this outside of typo fixes and doxygen. You wouldn't be able to see the effect of your changes, after all! -#. Make your first fix, push everything to your fork. -#. Once you're done, go to :menuselection:`merge requests` and press :guilabel:`new merge request` -#. Tell us what you've done in detail. +#. Set up a new remote which points to the official repository, so you'll be able to update your master branch. + + .. code-block:: bash + + # for ssh access + git remote add upstream git@invent.kde.org:kde/krita.git + # for https access + git remote add upstream https://invent.kde.org/kde/krita.git + + After that, you can see all of your links using: + + .. code-block:: bash + + git remote --verbose + + As you can see, `origin` points to your fork, while `upstream` points to the official repository. + +#. Create a new branch and checkout to it. + + .. code-block:: bash + + git checkout -b "/" + +#. Make your first fix, push everything to your branch in your fork. + + .. code-block:: bash + + # make sure you didn't leave any necessary debug or unfinished code + git diff + # stage all changes + git add . + # make sure all added files are the ones you want to have in your commit + git status + # commit changes (write a commit messages that follows the rules) + git commit + # push to your branch + git push + + .. attention :: + + Make sure all of your commits goes to your own branch, not onto master. + + + +#. Once you're done, login to KDE gitlab instance, go to :menuselection:`merge requests` and press :guilabel:`new merge request` +#. Make sure your merge request is between your branch from your fork and the official master branch. +#. Write a detailed description about the changes that you are proposing with your merge request. If it is a change in the user interface, it would be good if you can provide screenshots through attachments. + +The Krita developers will be notified of new merge requests, and they will try to review your request as soon as possible. If you suspect your patch slipped through the cracks, don't hesitate to contact us through the means described above. + + +Update the master in your fork +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After working for some time, you may want to update the master branch of your fork to be in sync with master branch from the official repo. + +#. Checkout the master branch in your working environment. + + .. code-block:: bash + + git checkout master + +#. Pull the changes from official repository. + + .. code-block:: bash + + git pull --ff-only upstream master + + +#. Push it to your fork. + + .. code-block:: bash + + git push + + +The other possibility is to just delete the fork you worked previously on and create another one - it will be up-to-date with official repository master already. + + +Label workflow +~~~~~~~~~~~~~~ + +Make sure the state of your merge request is labeled correctly. The picture below shows the basic label workflow that your merge request should go through: + +.. image:: ../images/en/Merge_Request_Label_Workflow.png + :width: 1000px + + +#. When you create a merge request, mark it with WIP to make sure no one will accidentally merge your request prematurely. +#. When you finish your work, label it with ``Needs Review``. That will make developers know your merge request is ready. +#. A Krita developer will read and test your merge request. After that they will write comments and label your merge request accordingly: + + * if the merge request is ready to be merged, with ``Approved`` label; + * if it requires changes to proceed, with ``Needs Changes`` label. + +#. If your merge request is in ``Needs Changes`` state, please follow the instruction of the reviewer and submit the code to your merge request. Add ``Needs Review`` label to your MR again. +#. When your merge request is in the ``Approved`` state, you can either merge the code yourself to master if you have developer access, or wait for KDE developer to do it for you. + +.. attention:: + If you have developer access and merge someone's merge request to the repository, you are partially responsible for the code. + + * Don't merge MRs that weren't approved! + * Read and test extensively all MRs before you approve or merge! + + + +How to prepare your commits for merge request +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After merging to master, your commits should nicely fit in the Krita git history. + +* Commit messages should clearly and concisely state what changes you made with that particular commit and why - see `How to Write a Git Commit Message `_. + +* Every commit should be compilable and follow the KDE commit guidelines - see `KDE Commit Policy `_. + +* Commits should be self-contained: if you code a bigger feature, it's better if you divide the code into bits that can possibly exist independently. + +* When you add new features during the development, it's fine to add new commits. + +* If you need to only fix previous commits, don't add new ones - instead, amend the ones that you made before and force-push your new commits to the branch in your fork. + + .. code-block:: bash + + # if you already committed your changes... + git commit + # ...add all changed files the "staged" state + git add . + # and amend the previous commit + git commit --amend + + + .. note:: + You can only force-push to your own branch on your own fork. If you need to remove changes from one of the commits that are already in the official repository, please use ``git revert``. + + +* When you want to reduce the number of commits: + + * you can squash them before making a merge request, + * if you have developer access, you can squash the commits just before merging with master. + * `Beginner's guide to rebasing and squashing `_ + +* Your work should go to a new branch, instead of master. + +* Your commits will be rebased and put on master using fast-forward merge. If you need a manual merge (if, for example, you're working on a big feature) and you don't have the commit access, please contact a Krita developer. + + + + + + + + + + + + + + + + -The Krita developers be informed of new merge requests, and will try to review your request as soon as possible. If you suspect your patch slipped through the cracks, don't hesitate to make contact us through the means described above. .. https://forum.kde.org/viewtopic.php?f=288&t=125955