Git Guidelines

This page is mostly directed to core developers with commit access to upstream repositories.

For instructions on basic usage, see Git.

For determining who is allowed to do what, see Organisation.

For guidelines about overall pull request quality, see Merging core pull requests to upstream.

Upstream branch rules

The master branch is not used for feature freezes. A new feature freeze branch is created when a release is to be made, to which bugfixes are applied until it's considered stable. (It can be extended to be a more complete release model later, but this is the important part for now.) ^{(https://forum.minetest.net/viewtopic.php?f=3&t=11172)}

Upstream pull requests and issues

• If a pull request or an issue does not get a response from its author in one month (when requiring more details), it is closed.
• If an issue is a duplicate, refer to the first one and close the later ones.

Upstream commit rules

1. You can push something to upstream [1] only if two members of the core team [2] or the subsystem maintainer agrees on it. (See Organisation.)
2. Commit messages must start with a capital letter and be in the present tense (look at the commit log)
3. Do not modify history older than 10 minutes
4. Use rebase, not merge, to get linear history. [3]

Notes

[1] Upstream is at https://github.com/minetest

[2] The team: https://github.com/minetest?tab=members

[3] For a github pull request, this is easiest done by appending .patch to the pull request URL, wgetting it to your project directory and doing git am whatever.patch. Similarly for single commits.

Rule 1 in practice

Tell people openly what you do, and if someone finds a problem in what you do, allow resolving to take it's time. Communicate both, the big goals and the important details beforehand to lessen wasted work.

If you have a small patch, fixing some compiler error or other trivial mistake, notify about fixing it on #minetest-dev, wait for 5...15 minutes and push it. To save time, you should notify when finding the problem, not when having it fixed. If someone asks something about it, delay pushing and link the patch [1] or tell whatever else people want to know.

If you have a medium-sized patch, usually containing 5...50 changed lines, you often should have already notified people about what you started doing. Link the patch [1] on #minetest-dev and wait until people notice it. Link again later or the next day or next week if needed. [2] Merge after more people agree than disagree on it, and prepare to rework it more or less if needed. Aim for a consensus.

If you have a large patch, containing >100 changed lines, you should have notified on #minetest-dev when you started coding it, telling what problem or missing feature you are addressing and/or noting midway what specific approach you took. When notifying the first time, try to make sure [2] someone knowledgeable approves your goal and doesn't disagree with your approach. Continue like with a medium-sized patch.

In general

It is always polite to give more time for people to look at your patch, especially if not many people are present. It also lets you take a break and think, and generally nothing is lost. If you fear people judging you, you have even more reason to communicate.

Some people tend to overly and negatively react to certain kinds of things. In these cases it's best to just let the steam first go out and then move to a less escalated and more factful discussion, forgetting the initial reaction.

This text only refers to patches that you want to get to upstream soon. You are encouraged to code proof-of-concept patches of all sizes for discussion and testing without intention to push them upstream.

It is a good idea to do the same to others that you want them to do to you; that is, look at their patches even if they don't really interest you or you aren't perfectly familiar with the subject.

Notes

[1] Patches can be linked using a pastebin or by using github (pull request or not).

[2] It's really some kind of an interestocracy. If nobody is interested of something, you should wait for a silent moment and then eg. explain what it does; how much the current version sucks and how little it sucks after the patch; what kind of performance measurements you made; tell people what to try to do to easily see a problem. Try telling the big picture or a detail. --Celeron55 (talk) 01:14, 5 August 2013 (MSK)