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)

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

To do this automatically for all your forked repository, create a file pull_from_upstream.sh in your ~/bin directory and paste the following text into it:

#!/bin/bash
set -e

CURDIR=`pwd`
REPOS=/home/luc/work

function pull() {
    repo=$REPOS/$1
    cd $repo
    echo "Pulling to $repo ..."
    git fetch upstream
    default=$(basename $(git symbolic-ref --short refs/remotes/origin/HEAD))
    git merge upstream/$default
    cd $CURDIR
}

# Call `pull` for each repository that you forked:

pull lino
pull xl
pull book
...

# Run `git pull` on all projects. It's useless but harmless in the one's you
# forked:

per_project git pull

After creating the file you must run chmod +x ~/bin/pull_from_upstream.sh to make it executable.

How to create your `~/bin` directory ¶

~/bin¶

The ~/bin directory is meant to contain scripts that you write for yourself.

If you do not yet have a ~/bin directory, you can create it as follows:

$ mkdir ~/bin

Note that after creating this directory, the system will not yet find any executable file contained in this directory because your .profile script adds it to your PATH only when it exists. And your .profile executes only when you log in. You can simulate a new login by saying:

$ source ~/.profile

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

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:

How to make pull requests *without* a GitHub account? (2012-03-09)
The git request-pull command.

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 🙂