2bda61e74d
a bunch of (typo) fixes, additions, rewordings Update references - remove mentions of the master branch, as it's removed for many repos and might change in the future for others (fixes some dead links) - remove mentions of moved repos with our official examples - some on-the-fly additions or rewordings Close #186 foobar->examples Co-authored-by: fnetx <git@fralix.ovh> Co-authored-by: fnetX <git@fralix.ovh> Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/189 Co-authored-by: Otto Richter <fnetx@noreply.codeberg.org> Co-committed-by: Otto Richter <fnetx@noreply.codeberg.org>
84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
---
|
|
eleventyNavigation:
|
|
key: PullRequestsGitFlow
|
|
title: Pull requests and Git flow
|
|
parent: Collaborating
|
|
order: 20
|
|
---
|
|
|
|
## Benefits of a pull-request based workflow
|
|
|
|
> ***TLDR:*** *Keep an eye on your repository and org permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners need full access to the repo to merge them.*
|
|
|
|
Although it is perfectly possible to use a Git project on Codeberg just as single shared central repository for individuals and teams, a collaborative workflow based on pull requests provides many benefits:
|
|
|
|
- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests. Contributors can easily work on forked repositories.
|
|
- Each pull request collects the full edit history for a fix or feature branch. Contributors can squash this, or keep it, just as they prefer.
|
|
|
|
### Cheat sheet
|
|
|
|
Let's say, you would like to contribute to our "examples" project [knut/examples](https://codeberg.org/knut/examples).
|
|
|
|
First, fork the project you would like to work on, by clicking the `fork` button in the top-right corner of the project page:
|
|
|
|
|
|
|
|
Then clone it onto your local machine. We assume that [you have set up your SSH keys](/security/ssh-key). This has to be done only once:
|
|
|
|
```shell
|
|
git clone git@codeberg.org:<YOURCODEBERGUSERNAME>/examples.git
|
|
```
|
|
|
|
Now, let's create a feature branch, do some changes, commit, push, edit, commit, push, ..., edit, commit, push:
|
|
|
|
```shell
|
|
git checkout -b my_cool_feature_branch
|
|
## do some changes
|
|
git commit -m "first feature"
|
|
git push ## here you get asked to set your upstream URL, just confirm
|
|
## do more work, edit...
|
|
git add new_file.png
|
|
git commit -m "second feature introducing a new file"
|
|
git push
|
|
## ...
|
|
git commit -m "more work, tidy-up"
|
|
git push
|
|
```
|
|
|
|
Now you can create the pull request by selecting your feature branch, and clicking on the pull request button:
|
|
|
|
|
|
|
|
### Keep it up-to-date: rebase pull requests to upstream
|
|
|
|
Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
|
|
|
|
In order to track the `upstream` repository, we add a second remote that is pointing to the original project. This has to be done only once:
|
|
|
|
```shell
|
|
git remote add upstream git@codeberg.org:knut/examples.git
|
|
```
|
|
|
|
You can also use the SSH variant here for public projects, if you want to be
|
|
able to pull without specifying your credentials.
|
|
|
|
Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository (e.g. the `main` branch):
|
|
|
|
```shell
|
|
git pull --rebase upstream main
|
|
git pull
|
|
```
|
|
|
|
That's it. You can now push your changes, and create the pull request as usual by clicking on the "pull request" button.
|
|
|
|
## A friendly note on owner rights, and forced push permissions
|
|
|
|
Please keep in mind that project owners can do *everything*, including editing and rewriting the history using `force-push`. In some cases this is a useful feature
|
|
(for example to undo accidental commits or clean up PRs),
|
|
but in most cases a transparent history based on a pull-request based workflow is surely preferable,
|
|
especially for the default branches of your project where other people rely on intact history.
|
|
|
|
**Warning** If you accidentally leaked sensitive data, say, leaked credentials,
|
|
keep in mind that commits stay directly accessible, e.g. from the user
|
|
activity tab or a Pull Request feed, for a while.
|
|
Please contact us if you really need to remove such data from the public.
|