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

Jump to bottom

update contribution guide #1320

Merged
merged 4 commits into from
Aug 10, 2023
Merged

update contribution guide #1320

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
af4dfc6
update contribution guide
maliagehan Aug 3, 2023
9860fa0
Update CONTRIBUTING.md
maliagehan Aug 3, 2023
f7bae0f
Merge branch 'release-4.0' into add-tutorial-guide
nfahlgren Aug 10, 2023
08a610f
Update py.test and mkdocs commands
nfahlgren Aug 10, 2023
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
100 changes: 77 additions & 23 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,21 @@
# How to contribute
# Table of Contents for Contibution
1. [Overview of Contribution](#overview)
2. [Creating Issues](#creatingissues)
3. [Contributing Text or Code](#textcode)
* [Set-Up Development Environment](#devenvironmment)
* [Clone the Source Code](#clone)
* [Install PlantCV dependencies](#install)
* [Create a Branch](#branch)
* [Work and Commit](#commit)
* [Testing and documenting your code](#testdoc)
* [Publish and Create Pull Request](#publish)
4. [Guidelines for New Features](#newfeatures)
* [New Function Style Guide](#style)
5. [Instructions for Adding A New Tutorial](#tutorial)
* [Create Your Tutorial Repository](#repo)
* [Add Your Tutorial to the Gallery Wall](#gallery)

## Overview Of What To Contribute <a name="overview"></a>

This document aims to give an overview of how to contribute to PlantCV.
We encourage contributions in a variety of forms. There are
Expand All @@ -14,10 +31,11 @@ There are many ways to contribute:
* Add unit tests
* Revise existing code
* Add or revise documentation
* Add, update, or revise a use-case tutorial

If you need any help, please contact us.

## Creating Issues
## Creating Issues <a name="creatingissues"></a>

- Make sure you have a GitHub account.
- Search GitHub and Google to see if your issue has already been reported
Expand All @@ -27,21 +45,19 @@ If you need any help, please contact us.
- Make sure you fill in the earliest version that you know has the issue.
- Where applicable, provide the full workflow prior to the error and the image getting analyzed.

## Contributing Text or Code

### Overview
## Contributing Text Or Code <a name="textcode"></a>

When you add a significant **new feature**, please create an issue
first, to allow others to comment and give feedback.

When you have created a new feature or other changes to existing
**Adding Or Changing Code** When you have created a new feature or other changes to existing
code, create a 'pull request'.

**Branching and Pull Requests**: All contributors to PlantCV code or documentation are required to use the
**Branching And Pull Requests**: All contributors to PlantCV code or documentation are required to use the
*feature branch workflow* (below) in order to allow pull
requests, automated testing, and code review.

### Setting up a development environment
### Setting Up A Development Environment <a name="devenvironmment"></a>

!!! note
Before setting up a development environment, choose between one of two methods for working with the PlantCV
Expand All @@ -50,18 +66,18 @@ requests, automated testing, and code review.
request to be added as a collaborator on the PlantCV repository so that you can work with it directly instead of
having to manage a separate repository.

#### Clone the source code from GitHub
#### Clone The Source Code From GitHub <a name="clone"></a>

After choosing a method above for accessing PlantCV source code, create a clone of the source code GitHub repository
using one of the methods described in the
[GitHub cloning a repository guide](https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/cloning-a-repository).

#### Install PlantCV dependencies
#### Install PlantCV Dependencies <a name="install"></a>

We recommend using `conda` to set up a virtual environment for developing PlantCV. Instructions can be found in the
[installation documentation](installation.md#installation-from-the-source-code).

#### Create a branch to do your work
#### Create A Branch To Do Your Work <a name="branch"></a>

The PlantCV default branch is protected and does not allow direct modification. A better practice is to
[create a branch](https://docs.github.com/en/free-pro-team@latest/desktop/contributing-and-collaborating-using-github-desktop/managing-branches)
Expand All @@ -70,12 +86,12 @@ number. This makes it easier to find out the issue you are trying to solve and h
the branch. Calling a branch my-work is confusing. Names of branch can not have a space, and should be replaced with
a hyphen.

#### Work and commit
#### Work And Commit <a name="commit"></a>

Do your work and commit as you see fit to check your work into your branch. Descriptive commit messages and
descriptions are helpful for understanding the purpose of changes.

#### Testing and documenting your code
#### Testing And Documenting Your Code <a name="testdoc"></a>

In addition to adding a new feature, test your code thoroughly:

Expand All @@ -87,18 +103,18 @@ the coverage the more likely we are to catch problematic pull requests). To incl
tests (to make sure they aren't broken by future pull requests) we need a 'unit test' or set of 'unit tests' (if you
need more than one test to cover function options).

Existing unit tests can be found in `tests/tests.py` as examples.
The data to support unit tests can be found in the `tests/*data/` directories.
Existing unit tests can be found in `tests/` as examples.
The data to support unit tests can be found in the `tests/testdata/` directory.

If you are updating existing code, make sure that the `test.py`
script passes on the function you modified. Testing locally can be done with pytest:
If you are updating existing code, make sure that the test(s) pass on the function you modified.
Testing locally can be done with pytest:

```bash
pytest tests/tests.py
py.test --cov=plantcv

# Or you can just run a subset of tests to save time
# This will run all tests with "analyze" in the test name
pytest tests/tests.py -k analyze
py.test --cov=plantcv -k analyze

```

Expand All @@ -108,11 +124,11 @@ be added to the `mkdocs.yml` file. You can test that your new documentation can
mkdocs from the root of your local plantcv repository.

```bash
mkdocs build --theme readthedocs --site-dir _site
mkdocs serve --theme readthedocs

```

#### Publish your branch to GitHub and create a Pull Request
#### Publish Your Branch To GitHub And Create A Pull Request <a name="publish"></a>

[Publishing your branch](https://docs.github.com/en/free-pro-team@latest/desktop/contributing-and-collaborating-using-github-desktop/managing-branches#publishing-a-branch)
to GitHub will make it available for creating a pull request between the updates and the default branch of PlantCV.
Expand All @@ -128,7 +144,7 @@ will automatically update when the branch is updated. Once tests pass, coverage
review is approved, the branch will be merged with the default branch and the updates are now part of the latest
version of PlantCV!

### Guidelines for adding new features
### Guidelines For Adding New Features <a name="newfeatures"></a>

In general, new contributions to PlantCV should benefit multiple users
and extend the image processing or trait analysis power of PlantCV.
Expand All @@ -147,7 +163,7 @@ We do hope that if you are contributing new methods to PlantCV, you are also con
tests for your functions (described below), because you understand your code/functionality best. If you have questions
or need help don't hesitate to ask [here](https://github.com/danforthcenter/plantcv/issues).

#### New function style guide
#### New function Style Guide <a name="styleguide"></a>

Include commenting whenever possible.

Expand Down Expand Up @@ -263,6 +279,44 @@ def new_function_calling_plantcv(img):

```

### Instructions for Adding A New Tutorial <a name="tutorial"></a>

We are always looking for new examples of how people are applying
PlantCV to their research. You can send us a Jupyter Notebook and any required sample data or
you can directly contrubute your tutorial. These instructions also apply to updating existing tutorials
that might break wth new versions of PlantCV.

#### Create Your Tutorial Repository <a name="repo"></a>

1. Create a new repository on GitHub (Please consider creating your repo within an instituional account rather than a personal account e.g. Danforth Center). The name should start with plantcv-tutorial. When you make this repo you can use the option to import the tutorial template from `https://github.com/danforthcenter/plantcv-tutorial-template`

2. If you don't import the tutorial template when you make your repo intitally you can clone the [tutorial template repository](https://github.com/danforthcenter/plantcv-tutorial-template) and copy the files and folders from the template repository to your tutorial repository

3. Update the `README` and `index.ipynb` files with your tutorial content, including data (make sure you are updating or using the correct documentation branch, e.g. release-4.0)

4. Add an image called `tutorial_card.png` to the repo, this will be used on the gallery webpage. The image should be approximately square and have a width of 200px.

5. Follow the instructions to create a Binder button in the readme

6. Commit the changes to your tutorial github repository

7. Go to your repo online and test the 'Launch Binder' button for your repo

#### Add Your Tutorial To the PlantCV Tutorial Gallery <a name="gallery"></a>

1. In your PlantCV repo make a new branch (make sure your branch is based off the version you are working on e.g. release-4.0)

2. Go to `/plantcv/docs/tutorials.md`, add a section for your new tutorial or update the binder links and link to your tutorial wall image

3. Either go to `/plantcv/docs/tutorials/'yourtutorialname'` and update the binder links and nb viewer links for your tutorial or go to `/plantcv/docs/tutorials/`
and add a doc with your tutorial name (use an exisiting tutorial as an example)

4. While in your plantcv directory check the build of the documentation on the command line by the command:
```
mkdocs serve --theme readthedocs
```
5. If everything looks okay then commit changes and make a pull request (make sure that pull request is for the for version you are working on).

### Thanks

Parts of this contribution guide are based on the
Expand Down