Skip to content

Latest commit

 

History

History
182 lines (125 loc) · 6.24 KB

CONTRIBUTING.md

File metadata and controls

182 lines (125 loc) · 6.24 KB
Raw

Contributing to pyroscrapper

Everything you need to know to contribute efficiently to the project.

Whatever the way you wish to contribute to the project, please respect the code of conduct.

Continuous Integration

This project uses the following integrations to ensure proper codebase maintenance:

  • Github Worklow - run jobs for package build and coverage
  • Codacy - analyzes commits for code quality
  • Codecov - reports back coverage results

As a contributor, you will only have to ensure coverage of your code by adding appropriate unit testing of your code.

Issues

Use Github issues for feature requests, or bug reporting. When doing so, use issue templates whenever possible and provide enough information for other contributors to jump in.

Code contribution

In order to contribute to project, we will first set up the development environment, then describe the contributing workflow.

Project Setup

In order to enable every one to fluently contribute to the project, we are going to set up the project properly following some steps:

  1. Create a virtual environment to avoid collision with our OS and other projects
  2. Fork the project to be able to start working on a local copy of the project

1. Create a virtual environment

We are going to create an python3.10 environment with dedicated to Pyro project. We'll use virtualenvwrapper.

Please open a terminal and follow the instructions.

# install package
pip install virtualenvwrapper

# add at the end of your .bashrc
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

# list available virtual environments
workon

# create new environment dubbed "pyro310" using python 3.10
mkvirtualenv -p $(which python3.10) pyro310

# activate pyro310 environment
workon pyro310

# deactivate the current environment
deactivate

# delete virtual environment (only do it if needed)
rmvirtualenv pyro310

2. Fork the repository

We are going to get a local copy of the remote project (fork) and set remotes so we stay up to date to recent contributions.

  1. Create a fork by clicking on the fork button on the current repository page
  2. Clone your fork locally.
# change directory to one for the project
cd /path/to/local/pyronear/project/

# clone your fork. replace YOUR_USERNAME accordingly
git clone https://github.com/YOUR_USERNAME/pyro-scrapper.git

# cd to pyro-scrapper
cd pyro-scrapper
  1. Set remotes to original project and merge new contributions onto master.
# add the original repository as remote repository called "upstream"
git remote add upstream https://github.com/pyronear/pyro-scrapper.git

# verify repository has been correctly added
git remote -v

# fetch all changes from the upstream repository
git fetch upstream

# switch to the master branch of your fork
git checkout master

# merge changes from the upstream repository into your fork
git merge upstream/master
  1. install the project dependencies
# install dependencies
pip install -r requirements.txt

# install current project in editable mode,
# so local changes will be reflected locally (ie:at import)
pip install -e .

Contributing workflow

Once the project is well set up, we are going to detail step by step a usual contributing workflow.

  1. Merge recent contributions onto master (do this frequently to stay up-to-date)
# fetch all changes from the upstream repository
git fetch upstream

# switch to the master branch of your fork
git checkout master

# merge changes from the upstream repository into your fork
git merge upstream/master

Note: Since, we are going to create features on separate local branches so they'll be merged onto original project remote master via pull requests, we may use pulling instead of fetching & merging. This way our local master branch will reflect remote original project. We don't expect to make changes on local master in this workflow so no conflict should arise when merging:

# switch to local master
git checkout master

#  merge remote master of original project onto local master
git pull upstream/master
  1. Create a local feature branch to work on
# Create a new branch with the name of your feature
git checkout -b pioneering-feature-branch

  1. Commit your changes (remember to add unit tests for your code). Feel free to interactively rebase your history to improve readability. See Commits section to follow guidelines.

  2. Rebase your feature branch so that merging it will be a simple fast-forward that won't require any conflict resolution work.

# Switch to feature branch
git checkout pioneering-feature-branch

# Rebase on master
git rebase master
  1. Push your changes on remote feature branch.
git checkout pioneering-feature-branch

# Push first time (we create remote branch at the same time)
git push -u origin pioneering-feature-branch

# Next times, we simply push commits
git push origin
  1. When satisfied with your branch, open a PR from your fork in order to integrate your contribution to original project.

Commits

  • Code: ensure to provide docstrings to your Python code. In doing so, please follow Google-style so it can ease the process of documentation later.
  • Commit message: please follow Udacity guide