Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

Submit your first pull request

Send a patch

The easiest and most basic way of contributing a code change is to send a patch. Here is how to do that.

  • Go to the project root directory and type:

    $ git diff > mypatch.txt

  • Send the file mypatch.txt or its content via e-mail to a committer (somebody who has write permission to the public code repositories).

A disadvantage of this method is that you won’t be visible as the contributor in the history of the repository. That’s why our recommended way of making pull requests is to use a fork. Read on.

Create a fork

Create a fork of the repositories you are going to work on.

  • Go to https://gitlab.com/lino-framework/xxx (where xxx is the nickname of the Lino repository, like “lino”, “xl”, “book”, “noi”, etc…)

  • Sign in (if you didn’t already)

  • Click the “Fork” button and answer the questions GitLab asks you

  • The URL of your fork will be something like https://gitlab.com/joedoe/xxx

Point your local repository to use your fork

  • Make sure that you have no local changes in your clone of the repository. Say git status to see whether your copy is clean. If you have already local work done, be careful to not lose your changes. Say git diff > mypatch.txt to have a patch just in case. Say git stash to move your changes aside.

  • Update the origin remote of your clone so that it syncs to your fork rather than the official lino repository:

    $ git remote set-url origin git@gitlab.com:joedoe/xxx.git

  • Add an upstream remote to your local copy so that it points to your fork:

    $ git remote add upstream git@gitlab.com:lino-framework/xxx.git

  • Verify that your remotes are correct:

    $ git remote -v
origin      git@gitlab.com:joedoe/xxx.git (fetch)
origin      git@gitlab.com:joedoe/xxx.git (push)
upstream    git@gitlab.com:lino-framework/xxx.git (fetch)
upstream    git@gitlab.com:lino-framework/xxx.git (push)

Submit a pull request

  • Start editing the files in your local clone of the repository. If you previously used git stash to put aside some local changes, then now it’s time to restore them:

    $ git stash pop

  • Publish your local changes to your public repository using git commit and git push. You need to use an SSH key. See Use SSH keys with GitLab

  • Run git request-pull

Pull changes from upstream to your fork

The official upstream repositories are under active development, so you probably want to merge the latest changes into your fork as often as possible. Here is how to do this:

git fetch upstream
git merge upstream/master

Using git request-pull

The problem with using GitHub pull requests is that this approach partly relies on proprietary software. I don’t know whether this applies to GitLab as well. Linus Thorvalds explained why he doesn’t do GitHub pull requests in a comment on 2012-05-11 (broken link, archived here):

I don’t do github pull requests.

github throws away all the relevant information, like having even a valid email address for the person asking me to pull. The diffstat is also deficient and useless.

Git comes with a nice pull-request generation module, but github instead decided to replace it with their own totally inferior version. As a result, I consider github useless for these kinds of things. It’s fine for hosting, but the pull requests and the online commit editing, are just pure garbage.

I’ve told github people about my concerns, they didn’t think they mattered, so I gave up. Feel free to make a bugreport to github.

Some more thoughts about this:

Pushing directly to the master (main) branch?

Hell is when people push directly to master branch. That’s at least what this thread on Reddit suggests. The resulting discussion is interesting. Obviously there are different religious schools about the topic. Well-educated project managers seem to be horrified and ask “Who lets people push to master without a pull request and code review?”, but others have obviously been in that “hell”, and they report quite positive things about it:

  • It depends on what the workflow for git is. If you CI/CD deploys to production on a push to master, well you shouldn’t push to master obviously. If “master” is the bleeding edge branch that may be broken from time to time, then it’s not that big of a big deal. For example, Google does it that way in Flutter. Master is only “Usually functional, though sometimes we accidentally break things.”. After testing, master gets merged into “dev”, then “beta”, then “stable”.

  • We push to master in my current role and I have in all my jobs for the last 10+ years. We do ci/cd, feature toggles and automated testing. Pairing is how we do code reviews. Honestly nothing wrong with it 🙂

See also