Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update contributing guidelines #394

Merged
merged 1 commit into from
Jul 4, 2020
Merged

update contributing guidelines #394

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 63 additions & 75 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,116 +1,104 @@
# Contributing Guidelines

This document is inspired by similar instructions from GMT, ISCE, gdal and jupyterhub. If you're reading this section, you're probably interested in contributing to MintPy. Welcome and thanks for your interest in contributing!
This document is inspired by similar instructions from numpy, GMT, ISCE, gdal and jupyterhub. If you're reading this section, you're probably interested in contributing to MintPy. Welcome and thanks for your interest in contributing!

These are several ways to contribute to the MintPy project:

* Submitting bug reports, feature requests on [GitHub issue](https://github.com/insarlab/MintPy/issues)
* Writing/improving documentation, tutorials and jupyter-notebooks
* Fixing typos, bugs in code
* Writing or proofreading documentation (including tutorials and examples in jupyter-notebooks)
* Submitting bug reports or feature requests on [GitHub issue](https://github.com/insarlab/MintPy/issues)
* Suggesting or implementing tests
* Fixing typos or bugs in code
* Writing code for everyone to use
* Giving feedback about the projects (including giving feedback about the contribution process)

If you get stuck at any point you can create an [issue on GitHub](https://github.com/insarlab/MintPy/issues) or contact us on the [user forum](https://groups.google.com/forum/#!forum/mintpy).
If you get stuck at any point you can open an [issue on GitHub](https://github.com/insarlab/MintPy/issues) or comment on any open issue or pull request or contact us on the [user forum](https://groups.google.com/forum/#!forum/mintpy).

For more information on contributing to open source projects, [GitHub's own guide](https://guides.github.com/activities/contributing-to-open-source/)
is a great starting point if you are new to version control. Tute Costa has a great [tutorial on how to rewrite history with git rebase/squash/amend](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history).
is a great starting point if you are new to version control.

## Writing documentations ##
## Development process ##

Documentation is written in Markdown. ANY GitHub user can edit pages and/or create new pages on [GitHub Wiki](https://github.com/insarlab/MintPy/wiki) directly for documentation, examples, support, or anything you wish. Eventually, mature documents on the wiki will be moved to the `insarlab/MintPy/docs` through standard code review process to be shown in the [readthedocs](https://mintpy.readthedocs.io/en/latest/).
#### 1. If you are a first-time contributor: ####

## Writing code ##
+ Go to https://github.com/insarlab/MintPy.git and click "fork" button to create your own copy of the project.

We follow the [git pull request workflow](https://www.asmeurer.com/git-workflow/) to make changes to our codebase. Every change made goes through a pull request, even our own, so that our [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) services have a change to check that the code is up to standards. This way, the master branch is always stable.
+ Clone the project to your local computer and add the upstream repository:

### General guidelines for pull requests (PRs) ###
```
git clone https://github.com/your_user_name/MintPy.git
cd MintPy
git remote add upstream https://github.com/insarlab/MintPy.git
```

+ **Open an issue first** describing what you want to do, except for bugs fix. If there is already an issue that matches your PR, leave a comment there instead to let us know what you plan to do. We may have easier ways to help you implement it faster.
+ Each pull request should consist of a **small** and logical collection of changes.
+ Larger changes should be broken down into smaller components and integrated separately.
+ Bug fixes should be submitted in separate PRs.
+ Describe what your PR changes and why this is a good thing. Be as specific as you can. The PR description is how we keep track of the changes made to the project over time.
+ Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`, IDE project files, etc).
+ Write descriptive commit messages. Chris Beams has a [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit messages. Tute Costa has a great [tutorial](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history) on how to rewrite a nice and clean history with git rebase/squash/amend.
+ Be willing to accept criticism and work on improving your code; we don't want to break other users' code, so care must be taken not to introduce bugs.
+ Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.
+ Now, `git remote -v` will show two remote repositories named:

### Code Review ###
- `upstream`, which refers to the `insarlab` repository
- `origin`, which refers to your personal fork

After you've submitted a pull request, you should expect to hear at least a comment within a couple of days. We may suggest some changes or improvements or alternatives.
#### 2. Develop your contribution: ####

Some things that will increase the chance that your pull request is accepted quickly:
+ **Open an [issue](https://github.com/insarlab/MintPy/issues) first** if you want plan to introduce a new feature or to change funcationality, we may have easier ways to help you implement it. If there is already an issue that matches your idea, leave a comment there instead to let us know what you plan to do. For bug fixes, documentation updates, etc., this is generally not necessary.

+ Write a good and detailed description of what the PR does.
+ Readable code is better than clever code (even with comments).
+ Write documentation for your code and leave comments explaining the _reason_ behind non-obvious things.
+ Include an example of new features in the gallery or tutorials, if possible.
+ Pull the latest changes from upstream:

Pull requests will automatically have tests run by Circle CI and Codacy. Github will show the status of these checks on the pull request. Try to get them all passing (green). If you have any trouble, leave a comment in the PR or contact us on the [user forum](https://groups.google.com/forum/#!forum/mintpy).
```
git checkout master
git pull upstream/master
```

### Example workflow ###
+ Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name such as 'seasonal_fitting':

This is not a git tutorial by any means. It just collects a few best practice for git usage for MintPy development. There are plenty of good resources online to help get started.
```
git checkout -b seasonal_fitting
```

#### Set up a development environment ####
+ Work on your idea, run tests and commit locally (`git add` and `git commit`) and/or to your fork on GitHub as you progress (`git push` in command line or [GitHub Desktop](https://desktop.github.com/) with graphical user interface). Use a clear commit message describing the motivation of a change, the nature of a bug for bug fixes or some details on what an enchancement does.

Fork insarlab/MintPy from GitHub UI, and then
+ Run the [overall test](./CONTRIBUTING.md#testing) locally.

```
git clone https://github.com/my_user_name/MintPy.git
cd MintPy
git remote add upstream https://github.com/insarlab/MintPy.git
```
#### 3. To submit your contribution: ####

#### Work with a feature branch ####
+ Go to GitHub. The new branch will show up with a Pull request button. Click and fill out the pull request template, make sure the title and message are clear, concise, and self-explanatory (these descriptions are how we keep track of the changes made to the project over time). Then click the button to submit it.

```
# update to the latest upstream master
git checkout master
git fetch upstream
git rebase upstream/master
git push -f
git checkout -b my_new_feature_branch

# do work. For example:
git add my_new_file
git add my_modifid_message
git rm old_file
git commit -a

# you may need to re-synchronize against upstream/master
# if you need some bugfix or new capability that has been
# added to master since you created your branch
git fetch upstream
git rebase upstream/master

# At end of your work, make sure history is reasonable by:
# folding non significant commits into a consistent set
# use 'fixup' for example to merge several commits together
# use 'reword' to modify commit messages
# to re-write the last 5 commits for example:
git rebase -i HEAD~5

# push your local changes to your fork on GitHub
git push

# you may need to force-push your branch with
git push -f
```
#### 4. Review process: ####

We follow the [git pull request (PR) workflow](https://www.asmeurer.com/git-workflow/) to make changes to our codebase. Every change made goes through a PR, even our own, so that our [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) services have a change to check that the code is up to standards. GitHub will show the status of the these checks on the PR. Try to get them all passsing (green). If you have any trouble, leave a comment in the PR.

+ Reviewers (the other developers and interested community members) will write inline and/or general comments on your PR to help you improve its implementation, documentation and style. We don't want to break the shared codebase, so care must be taken not to introduce bugs. Please don’t let the review discourage you from contributing: its only aim is to improve the quality of project, not to criticize (we are, after all, very grateful for the time you’re donating!).

+ To update your PR, make your changes on your local repository, run tests, and only if they succeed commit and push to your fork. As soon as those changes are pushed up (to the same branch as before) the PR will update automatically. If you have no idea how to fix the test failures, you may push your changes anyway and ask for help in a PR comment.

#### Issue a pull request from GitHub UI ####

If the pull request discussion results in changes, commit new changes to `my_user_name/my_new_feature_branch`, they will show up in the pull request in `insarlab` automatically.
## Divergence between `upstream/master` and your feature branch ##

If GitHub indicates that the branch of your Pull Request can no longer be merged automatically, you have to incorporate changes that have been made since you started into your branch. Our recommended way to do this is to rebase on master. Tute Costa has a great tutorial on how to [rewrite history with git rebase/squash/amend](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history).


## General guidelines for pull requests (PRs) ##

+ Each pull request should consist of a **small** and logical collection of changes.
+ Larger changes should be broken down into smaller components and integrated separately.
+ Describe what your PR changes and why this is a good thing. Be as specific as you can. The PR description is how we keep track of the changes made to the project over time.
+ Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`, IDE project files, etc).
+ Write descriptive commit messages. Chris Beams has a [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit messages.
+ Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.

Some things that will increase the chance that your pull request is accepted quickly:

+ Write a good and detailed description of what the PR does.
+ Readable code is better than clever code (even with comments).
+ Write documentation for your code and leave comments explaining the _reason_ behind non-obvious things.


## Testing ##

It's a good idea to test any changes or bugs you have fixed, in the feature branch before issuing the pull request. We realize that we don't have a complete testing system in place yet (maybe you can contribute this!), except for an overall testing script `test_smallbaselineApp.py`, run
It's a good idea to test any changes or bugs you have fixed, in the feature branch before issuing the pull request. We realize that we don't have a complete testing system in place yet (maybe you can contribute this!), except for an overall testing script `test_smallbaselineApp.py`:

```
${MINTPY_HOME}/test/test_smallbaselineApp.py
```

to see the testing result, it takes about 10 mins to finish.
It takes about 10 mins to finish.


## Things you should NOT do ##
Expand Down
44 changes: 22 additions & 22 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ save_kmz.py #generate Google Earth KMZ file in raster image
save_kmz_timeseries.py #generate Goodle Earth KMZ file in points for time-series (interactive)
```

#### 2.2 Customized processing recipe: [example](https://github.com/insarlab/MintPy/blob/master/sh/compare_velocity_with_diff_tropo.sh) ####
#### 2.2 Customized processing recipe ####

MintPy is a toolbox with individual utility scripts. Simply run the script with `-h / --help` to see its usage, you could build your own customized processing recipe! Here is an example to compare the velocities estimated from displacement time-series with different tropospheric delay corrections: [link](https://github.com/insarlab/MintPy/blob/master/sh/compare_velocity_with_diff_tropo.sh)
MintPy is a toolbox with individual utility scripts. Simply run the script with `-h / --help` to see its usage, you could build your own customized processing recipe! [Here](https://github.com/insarlab/MintPy/blob/master/sh/compare_velocity_with_diff_tropo.sh) is an example to compare the velocities estimated from displacement time-series with different tropospheric delay corrections.

#### 2.3 Build on top of `mintpy` module ####

Expand All @@ -82,32 +82,32 @@ ts_data, meta = readfile.read('timeseries_ERA5_ramp_demErr.h5')

Algorithms implemented in the software are described in details in [Yunjun et al. (2019)](https://doi.org/10.1016/j.cageo.2019.104331).

+ [Tutorials in Jupyter Notebook](https://github.com/insarlab/MintPy-tutorial)
+ [Example datasets](./demo_dataset.md)
+ [Quick start with example datasets](./demo_dataset.md)
+ [Example data directory](./dir_structure.md)
+ [Example template files for InSAR processors](./examples/input_files/README.md)
+ [Google Earth KMZ file](./google_earth.md)
+ [Tutorials in Jupyter Notebook](https://github.com/insarlab/MintPy-tutorial)

### 4. User Forum ###
### 4. Contact us ###

Join our google group [https://groups.google.com/forum/#!forum/mintpy](https://groups.google.com/forum/#!forum/mintpy) to ask questions, get notice of latest features pushed to you!
+ Most development discussion happens on GitHub. Feel free to [open an issue](https://github.com/insarlab/MintPy/issues) or comment on any open issue or pull request.
+ Join our google group [https://groups.google.com/forum/#!forum/mintpy](https://groups.google.com/forum/#!forum/mintpy) to ask questions or leave comments.

### 5. Citing this work ###

Yunjun, Z., H. Fattahi, F. Amelung (2019), Small baseline InSAR time series analysis: Unwrapping error correction and noise reduction, _Computers & Geosciences_, _133_, 104331, doi:[10.1016/j.cageo.2019.104331](https://doi.org/10.1016/j.cageo.2019.104331), [arXiv](https://eartharxiv.org/9sz6m/), [data & figures](https://github.com/geodesymiami/Yunjun_et_al-2019-MintPy).

In addition to the above, we recommend that you cite the original publications that describe the algorithms used in your specific analysis. They are noted briefly in the [default template file](../mintpy/defaults/smallbaselineApp.cfg) and listed in [here](./references.md).

### 6. Contributors [[guideline](./CONTRIBUTING.md)] ###

* Zhang Yunjun
* Heresh Fattahi
* Falk Amelung
* Scott Baker
* Joshua Zahner
* Alfredo Terreco
* David Grossman
* Emre Havazli
* Yunmeng Cao
* Andre Theron
* [Other community members.](https://github.com/insarlab/MintPy/graphs/contributors)
In addition to the above, we recommend that you cite the original publications that describe the algorithms used in your specific analysis. They are noted briefly in the [default template file](../mintpy/defaults/smallbaselineApp.cfg) and listed in the [references.md file](./references.md).

### 6. Contributing ###

**Imposter syndrome disclaimer:** We want your help. No, really.

There may be a little voice inside your head that is telling you that you're not ready to be an open source contributor; that your skills aren't nearly good enough to contribute. What could you possibly offer?

We assure you - the little voice in your head is wrong. If you can write code at all, you can contribute code to open source. Contributing to open source projects is a fantastic way to advance one's coding skills. Writing perfect code isn't the measure of a good developer (that would disqualify all of us!); it's trying to create something, making mistakes, and learning from those mistakes. That's how we all improve, and we are happy to help others learn.

**Being an open source contributor doesn't just mean writing code.** You can help out by writing or proofreading documentation, suggesting or implementing tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.

For more information, please read our [contributing guide](./CONTRIBUTING.md).

_This disclaimer was adapted from the [MetPy project](https://github.com/Unidata/MetPy)._
2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ nav:
- Example datasets: demo_dataset.md
- Example directory structure: dir_structure.md
- Example template files: examples/input_files/README.md
- Tutorials in Jupyter Notebook: https://github.com/insarlab/MintPy-tutorial
- Parallel processing with Dask: dask.md
- Tutorials in Jupyter Notebook: https://github.com/insarlab/MintPy-tutorial
- Output:
- Google Earth KMZ: google_earth.md
- HDF-EOS5: hdfeos5.md
Expand Down