It's completely fine to just submit a small pull request without first making an issue, but if it's a big change that will require a lot of planning and reviewing, it's best you start with writing an issue first.
The steps given below are for the main Redox project repository - submodules and other projects may vary, though most of the approach is the same.
If you marked your MR as ready don't add new commits, because it will trouble the Jeremy's review, making him lost time by reading the text again
If you need to add new commits mark the MR as draft again
- In an appropriate directory, e.g.
~/tryredox, clone the Redox repository to your computer using one of the following commands:
git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive
git clone email@example.com:redox-os/redox.git --origin upstream --recursive
- Use HTTPS if you don't know which one to use. (Recommended: learn about SSH if you don't want to have to login every time you push/pull!)
- If you used
bootstrap.sh(see Building Redox), the
git clonewas done for you and you can skip this step.
- Change to the newly created redox directory and rebase to ensure you're using the latest changes:
cd redox git rebase upstream master
- You should have a fork of the repository on GitLab and a local copy on your computer. The local copy should have two remotes;
upstreamshould be set to the main repository and
originshould be your fork. Log into Redox Gitlab and fork the Repository - look for the button in the upper right.
- Add your fork to your list of git remotes with
git remote add origin https://gitlab.redox-os.org/MY_USERNAME/redox.git
git remote add origin firstname.lastname@example.org:MY_USERNAME/redox.git
- Note: If you made an error in your
git remotecommand, use
git remote remove originand try again.
- Alternatively, if you already have a fork and copy of the repo, you can simply check to make sure you're up-to-date. Fetch the upstream, rebase with local commits, and update the submodules:
Usually, when syncing your local copy with the master branch, you will want to rebase instead of merge. This is because it will create duplicate commits that don't actually do anything when merged into the master branch.
git fetch upstream master git rebase upstream/master git submodule update --recursive --init
- Before you start to make changes, you will want to create a separate branch, and keep the
masterbranch of your fork identical to the main repository, so that you can compare your changes with the main branch and test out a more stable build if you need to. Create a separate branch:
git checkout -b MY_BRANCH
- Make your changes and test them.
Commit messages should describe their changes in present-tense, e.g. "
git add . --all git commit -m "COMMIT MESSAGE"
Add stuff to file.ext" instead of "
added stuff to file.ext". Try to remove duplicate/merge commits from PRs as these clutter up history, and may make it hard to read.
- Optionally run rustfmt on the files you changed and commit again if it did anything (check with
- Test your changes with
- Pull from upstream:
git fetch upstream git rebase upstream/master
- Note: try not to use
git pull, it is equivalent to doing
git fetch upstream; git merge master upstream/master.
Repeat step 10 to make sure the rebase still builds and starts.
Push your changes to your fork:
git push origin MY_BRANCH
On Redox GitLab, create a Merge Request, following the template. Describe your changes. Submit!
If your merge requests is ready, send the link on Redox Merge Requests room.
- Open the repository that you want and click in "Web IDE".
- Make your changes on repository files and click on "Source Control" button on the left side.
- Name your commits and apply them to specific branches (each new branch will be based on the current master branch, that way you don't need to create forks and update them, just send the proper commits to the proper branches, it's recommended that each new branch is a different change, more easy to review and merge).
- After the new branch creation a pop-up window will appear suggesting to create a MR, if you are ready, click on the "Create MR" button.
- If you want to make more changes, finish them, return to the repository page and click on the "Branches" link.
- Each branch will have a "Create merge request" button, click on the branches that you want to merge.
- Name your MR and create (you can squash your commits after merge to not flood the upstream with commits)
- If your merge request is ready, send the link on Redox Merge Requests room.
- Remember that if you use forks on GitLab web interface you will need to update your forks manually in web interface (delete the fork/create a new fork if the upstream repository push commits from other contributors, if you don't do this, there's a chance that your merged commits will come in the next MR).