Skip to content

Commit

Permalink
contributing: move GitHub workflow docs into separate file (OSGeo#3875)
Browse files Browse the repository at this point in the history
  • Loading branch information
@petrasovaa
petrasovaa authored Jun 20, 2024
1 parent 362ad48 commit 30751a0
Show file tree
Hide file tree
Showing 2 changed files with 190 additions and 163 deletions.
166 changes: 3 additions & 163 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,122 +8,13 @@ or explore <https://grass.osgeo.org/get-involved/>.

## Changing code and documentation

This guide covers contributing to the main version of GRASS GIS source
code which is in the branch called _main_.
It assumes that you have some very basic knowledge of Git and GitHub,
but if you don't just go through some tutorial online or ask on the
GRASS GIS developer mailing list.
To contribute changes to GRASS GitHub repository, use a
"fork and pull request" workflow. This [guide](./doc/development/github_guide.md)
leads you through a first time setup and shows how to create a pull request.

To contribute effectively, please familiarize yourself with our
[Programming Style Guide](./doc/development/style_guide.md).

### First time setup

* Create an account on GitHub.
* Install Git on your computer.
* Set up Git with your name and email.
* Fork the repository (by clicking the `Fork` button in the upper right corner
of the GitHub interface).
* Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):

```bash
git clone git@github.com:your_GH_account/grass.git
```

* Enter the directory

```bash
cd grass/
```

* Add main GRASS GIS repository as "upstream" (use HTTPS URL):

```bash
git remote add upstream https://github.com/OSGeo/grass
```

* Your remotes now should be "origin" which is your fork and "upstream" which
is this main GRASS GIS repository. You can confirm that using:

```bash
git remote -v
```

* You should see something like:

```bash
origin git@github.com:your_GH_account/grass.git (fetch)
origin git@github.com:your_GH_account/grass.git (push)
```

For the following workflow, it is important that
"upstream" points to the OSGeo/grass repository
and "origin" to your fork
(although generally, the naming is up to you).

### Update before creating a feature branch

* Make sure your are using the _main_ branch to create the new branch:

```bash
git checkout main
```

* Download updates from all branches from the _upstream_ remote:

```bash
git fetch upstream
```

* Update your local _main_ branch to match the _main_ branch
in the _upstream_ repository:

```bash
git rebase upstream/main
```

Notably, you should not make commits to your local main branch,
so the above is then just a simple update (and no actual
rebase or merge happens).

### Update if you have local changes

If `rebase` fails with "error: cannot rebase: You have unstaged changes...",
then move your uncommitted local changes to "stash" using:

```bash
git stash
```

* Now you can rebase:

```bash
git rebase upstream/main
```

* Get the changes back from stash:

```bash
git stash pop
```

### Creating a new feature branch

Now you have updated your local _main_ branch, you can create a feature branch
based on it.

* Create a new feature branch and switch to it:

```bash
git checkout -b new-feature
```

### Making changes

You can use your favorite tools to change source code or other files
in the local copy of the code. When making changes, please follow the
[Programming Style Guide](./doc/development/style_guide.md).

### Testing changes

Testing helps to ensure that the changes work well with the rest
Expand All @@ -145,57 +36,6 @@ For Python, run `black .` to apply standardized formatting. You can
also run linter tools such as Pylint which will suggest different improvements
to your code.

### Committing

* Add files to the commit (changed ones or new ones):

```bash
git add file1
git add file2
```

* Commit the change (first word is the module name):

```bash
git commit -m "module: added a new feature"
```

### Pushing changes to GitHub

* Push your local feature branch to your fork:

```bash
git push origin new-feature
```

### Pull request

When you push, GitHub will respond back in the command line to tell
you what URL to use to create a pull request. You can follow that URL
or you can go any time later to your fork on GitHub, display the
branch `new-feature`, and GitHub will show you a button to create
a pull request.

Alternatively, you can explore GitHub CLI tool (_gh_) which allows you
to do `git push` and create a pull request in one step with `gh pr create -fw`.

### After creating a pull request

GRASS GIS maintainers will now review your pull request.
If needed, the maintainers will work with you to improve your changes.

Once the changes in the pull request are ready to be accepted,
the maintainers will usually squash all your commits into one commit and merge it
to the _main_ branch.

Once the pull request is merged, it is a good time to update your
local _main_ branch in order to get the change you just contributed.

### Further notes

GRASS GIS maintainers use additional workflows besides the one described
above. These are detailed at <https://trac.osgeo.org/grass/wiki/HowToGit>

## Compilation

More often than not, in order to test the changes, you need to create
Expand Down
187 changes: 187 additions & 0 deletions doc/development/github_guide.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
# Guide to contributing on GitHub

This guide covers contributing to the GRASS GIS source,
specifically to the _main_ branch.
It assumes that you have some very basic knowledge of Git and GitHub.

## First time setup

1. Create an account on GitHub.
1. Install Git on your computer.
1. Set up Git with your name and email.
1. Fork the repository (by clicking the `Fork` button in the upper right corner
of the GitHub interface).
1. Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):

```bash
git clone https://github.com/your_GH_account/grass.git
```

1. Enter the directory:

```bash
cd grass/
```

1. Add the main GRASS GIS repository as "upstream" (use HTTPS URL):

```bash
git remote add upstream https://github.com/OSGeo/grass
```

1. Your remotes now should be "origin" which is your fork and "upstream" which
is this main GRASS GIS repository. You can confirm that using:

```bash
git remote -v
```

1. You should see something like:

```bash
origin https://github.com/your_GH_account/grass.git (fetch)
origin https://github.com/your_GH_account/grass.git (push)
upstream https://github.com/OSGeo/grass (fetch)
upstream https://github.com/OSGeo/grass (push)

```

For the following workflow, it is important that
"upstream" points to the OSGeo/grass repository
and "origin" to your fork
(although generally, the naming is up to you).

## Update before creating a feature branch

Make sure your are using the _main_ branch to create the new branch:

```bash
git checkout main
```

Download updates from all branches from the _upstream_ remote:

```bash
git fetch upstream
```

Update your local _main_ branch to match the _main_ branch
in the _upstream_ repository:

```bash
git rebase upstream/main
```

Notably, you should not make commits to your local main branch,
so the above is then just a simple update (and no actual
rebase or merge happens).

## Creating a new feature branch

Now you have updated your local _main_ branch, you can create a feature branch
based on it.

Create a new feature branch and switch to it:

```bash
git switch -c new-feature
```

## Committing

Add files to the commit (changed ones or new ones):

```bash
git add file1
git add file2
```

Commit the change. Write a meaningful commit message (first word is for example
the tool name):

```bash
git commit -m "tool: added a new feature doing X"
```

## Pushing changes to GitHub

Push your local feature branch to your fork:

```bash
git push origin new-feature
```

## Creating a pull request

When you push, GitHub will respond back in the command line to tell
you what URL to use to create a pull request (PR). You can follow that URL
or you can go any time later to your fork on GitHub, display the
branch `new-feature`, and GitHub will show you a button to create
a PR.

Alternatively, you can explore GitHub CLI tool (_gh_) which allows you
to do `git push` and create a PR in one step with `gh pr create -fw`.

## After creating a PR

GRASS GIS maintainers will now review your PR.
If needed, the maintainers will work with you to improve your changes.

Once the changes in the PR are ready to be accepted,
the maintainers will usually squash all your commits into one commit and merge it
to the _main_ branch.

Once the PR is merged, it is a good time to [update your
local _main_ branch](#update-before-creating-a-feature-branch) in order to get
the change you just contributed.

## Further notes

Here we cover common situations and how to deal with them:

### Update if you have local changes

Assumption is you are on the main branch and you are trying to update it.
If `git rebase` fails with `error: cannot rebase: You have unstaged changes...`,
then move your uncommitted local changes to "stash" using:

```bash
git stash
```

Now you can rebase:

```bash
git rebase upstream/main
```

Get the changes back from stash:

```bash
git stash pop
```

### Updating your PR from main

Updating your PR from the main branch is often referred to as rebasing a PR.
It comes into play in case there are changes in the main branch you need to
incorporate into your (feature or fix) branch before the PR can be merged,
you need to merge the upstream main into your branch:

```bash
git fetch upstream
git merge upstream/main
```

Git will ask you to edit the merge commit messsage, you can leave the default
and close the editor. You may run into a conflict,
in that case you need to resolve it.

### Testing PRs from other contributors

For testing other contributors' PRs, we recommend using
[GitHub CLI](https://cli.github.com/). To checkout a specific PR, run:

```bash
gh pr checkout <PR number>
```

0 comments on commit 30751a0

Please sign in to comment.