diff --git a/docs/_images/user/pull-request/fork-button.png b/docs/_images/user/pull-request/fork-button.png new file mode 100644 index 00000000..9fabcc7e Binary files /dev/null and b/docs/_images/user/pull-request/fork-button.png differ diff --git a/docs/_images/user/pull-request/pull-request-button.png b/docs/_images/user/pull-request/pull-request-button.png new file mode 100644 index 00000000..228fb763 Binary files /dev/null and b/docs/_images/user/pull-request/pull-request-button.png differ diff --git a/docs/user/index.md b/docs/user/index.md index 2dfb387d..7e37ad1e 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -12,14 +12,14 @@ involved in running it on their machines. - [Email Settings](./email-settings/) - [Forgejo Next](./forgejo-next/) - Collaborating with Others - - [Projects / Kanban boards](./project/) - - [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/) + - [Pull requests and Git flow](./pull-requests-and-git-flow/) - [Invite Collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/) + - [Labels](./labels/) - [Create and Manage an Organization](https://docs.codeberg.org/collaborating/create-organization/) - [Repository Permissions](./repo-permissions/) - [Resolve Conflicts](https://docs.codeberg.org/collaborating/resolve-conflicts/) + - [Projects / Kanban boards](./project/) - [Citable Code](https://docs.codeberg.org/collaborating/citable-code/) - - [Labels](./labels/) - [Automatically Linked References](./linked-references/) - [Blocking users](./blocking-user/) - [Profile customization](./profile/) diff --git a/docs/user/pull-requests-and-git-flow.md b/docs/user/pull-requests-and-git-flow.md new file mode 100644 index 00000000..515f1eaa --- /dev/null +++ b/docs/user/pull-requests-and-git-flow.md @@ -0,0 +1,88 @@ +--- +title: Pull requests and Git flow +license: 'CC-BY-SA-4.0' +origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/7bb8fa5ca559073c028805888195ee31b1f3d9c2/content/collaborating/pull-requests-and-git-flow.md' +--- + +## Benefits of a pull-request based workflow + +> **_TLDR:_** _Keep an eye on your repository and organization permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners have permission 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. + +## Create a pull-request + +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: + +![Fork a project](../_images/user/pull-request/fork-button.png) + +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:/examples.git +``` + +Now, let's create a feature branch, do some changes, commit, push, edit, commit, push, ..., edit, commit, push: + +```shell +git checkout -b feature +# 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 a pull request by visiting the main repository page and clicking on the `New Pull Request` button. + +![Create a pull request](../_images/user/pull-request/pull-request-button.png) + +This button is automatically shown if: + +- You are the pusher on a branch that still exists and that is not the default branch +- The push must occurred within the last 6 hours +- There is no open PR for this branch + +## 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'll 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 "New Pull Request" button. + +## A friendly note on owner rights, and force 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.