Includes tips and hints on forking, pulling and pushing, submitting the PR's, and how to make working with PR's easy.
You've identified a place in minetest where you want to change something, and you want to submit these upstream so that everyone can enjoy them!
The following instructions should take you through the entire process:
Clone minetest and minetest_gameYou should clone both projects as the two parts of minetest work together, and often changes in one require the other. The best way to test and verify that your changes work together is to fork and clone both and test them together.
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
- Code: Select all
git clone git@github.com:mygithubname/minetest
git clone git@github.com:mygithubname/minetest_game
Compile and run your copy, and make sure you're actually using the code from them both before proceeding - if you can't test your changes, you'll have strange unsolvable problems later.
BranchesEach change submitted upstream should be in a separate branch. This makes it easy to review and modify the changes, so it helps everyone. As a rule, one PR means one branch.
git branch fix_spelling_error
This creates a new branch. You can check that your newly created branch exists by typing
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
without options. You should see a
* sign in front of the active branch, and notice that it isn't set to the new branch, so you need to switch (
checkout) the newly created branch first, before you can work in it:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
Now we're ready to make changes. Go and edit a file like
lua_apl.txt or
game_api.txt and make a small text change. Use a text editor and don't forget to save your changes.
Before you can submit your changes, you'll need to commit them to the repository as a changeset. This makes the modifications to the file part of the recorded history, and it includes writing a description, and summary. Your name is also recorded as part of the history.
To see what changes you have that are not committed yet, type:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
You should see a
diff that displays the file name where you made changes, in a format that shows you easily to see what the part looked before, and after your change.
If the output looks correct, you can try to commit your changes. First, we tell git what files we would like to commit by
staging the changes in the file for commit:
git add lua_api.txt
Now your change is staged, and you could stage more files. Or edit the file again and stage it again. And then finally:
git commit
Note: at this point you're probably going to get a warning from git about git not knowing what your name and e-mail address are, if you're doing this for the first time ever. You can tell git who you are by doing the two following commands:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
- Code: Select all
git config --global user.name "John Doe"
git config --global user.email "john.doe@example.com"
Once you do that, and retry the git commit, you should get to the commit message.
Commit messageI'm going to include a rather blunt statement here that is critical to getting your changes even considered, let alone included. So please take this with all seriousness and open-mindness at heart.At best, your change, is a worthless piece of junk. It's going to break everything. It's going to offend people. It's going to hurt imaginary kittens (or puppies). And it's going to make everyone forget they had evolved to higher level humans and revert to levels of communication that certain species had mastered in the early Silurian.
For this reason, alone, you can not, ever, think that writing a commit message is
less important than writing the code change that you had written. It is in fact, the
most important part of your change.
You should take the act of writing a commit message and consider it the crowning
advertisement of your change. You should write it in
full sentences. You should write it in a
readable fashion, and you should be dead honest about it while you do. If your change makes only a marginal improvement, be
honest and acknowledge it.
So, start with the
Subject of the commit message. Write something in 50 characters or so that describes the change so that it can be recognized, but not something that explains it.
Bad choices for subjects are:
"beds"
"more fixes"
"stuff"
"change this member to be public to avoid conflicts with std::scream operator in ElementIteratorFunction, because C++11 standard does not make opaque frequencies denunciated for unknown reasons"
Good choices for subjects are:
"Make bed placement not overwrite blocks"
"Prevent crash in on_metadata_*"
"API change documentation for schematics"
"Avoid C++11 compatibility in iterators"
As you can see, it doesn't need to be long. Longer probably means that you are trying to explain the change, but this goes in the summary.
The Summary should describe, explain, and motivate the change, but not as to such depth that it copies what the code change does. Let's dive into each of these 3 elements:
describing the change is an extended version of the summary. You use it to tell readers and reviewers where your changes are in the code, when they would be affecting the program, and how extensive they are.
explain your change where needed. Often this isn't needed, but sometimes it may not be obvious, and so then you'd explain exactly what is changed, and why the change achieves the effect required.
Motivate your change by explaining that currently something is broken, or is badly optimized, or just ugly or misspelled. Also describe how your patch actually solves that problem, too.
All done? On to making a PR then:
First, we need to push our change to our fork of the project:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
- Code: Select all
git push origin fix_spelling_error:fix_spelling_error
This creates a new remote branch in your fork on github with the same name as the local branch name. It also pushes the changes to this branch.
Now you can browse to github and go to your fork of the project, and you should see a "Create Pull Request" button. Click on it and follow the instructions.
Need to redo a change? Easy, just change the file again, but this time:
git add <file changed>
git commit --amend
and now your existing commit will be
modified. Alternatively, you can look at
git rebase -i if you want to do more cool things with combining commits.
Once you're happy with your committed changes, and tested them, you can push your changes again to the same branch:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
- Code: Select all
git push origin fix_spelling_error:fix_spelling_error --force
Because the remote branch has the old change, we need to overwrite the change, hence the "force" option.
The PR will automatically see your new changes, but you should visit it and check it, and leave a comment that you have changed it so people can revisit and re-review the change.