Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (94 loc) · 3.76 KB

CONTRIBUTING.md

File metadata and controls

141 lines (94 loc) · 3.76 KB

How to contribute to the respository.

This guide is intended for anyone who wants to contribute to FEWSNET API Notebooks Repository. Whether you're fixing a bug, adding a feature, or improving documentation, your contributions are highly appreciated!

These are simple guidelines that need to be followed in order to contribute to this repository effectively.

Security Guidelines

  • Be Cautious with Personal Information:
    • Avoid committing sensitive data like passwords, API keys, or personal identifiers into source code. Make use of environment variables instead.
    • Be mindful of the personal information you share in public discussions, commit messages, and documentation.

Contributing Guide

This guide outlines the steps to contribute to this repository.

Step 1: Fork the Repository

Before you can make changes, you need to create a fork of this repository:

  1. Go to the repository URL
  2. In the top-right corner of the page, click the Fork button.

This creates a copy of the repository in your own GitHub account.

Step 2: Clone Your Fork

Clone your fork to your local machine:

git clone https://github.com/FEWS-NET/data-notebook-hub.git
cd your-cloned-repo

Step 3: Create a New Branch

# Create a new branch for your changes:
Copy code
git checkout -b your-new-branch-name

Step 4: Make Your Changes

Make changes in your local repository. Be sure to:

Keep changes small and focused. Follow any coding standards or guidelines specific to this project.

Keep the project structure:

project name/
│
├── notebook.ipynb/
│   
├── data/
│   ├── raw_data/
│
├── requirements.txt
│
└── README.md

How to generate requirements.txt file

We use pipreqsnb to generate the requirements.txt. The library only picks the libraries that have been imported in your notebook thereby ensuring minimal conflicts with other dependencies.

To generate the requirements.txt for your notebook:

  1. Navigate to your project root folder or where the jupyter notebook is stored.
  2. If you need the requirements for just one notebook, you can generate it using the command below:
pipreqsnb /path/to/notebook
  1. For instaces where there are more than 1 notebook in your project directory:
pipreqsnb

Before commiting the notebook with new changes, ensure you clear all outputs. This can be done using the Jupyter lab menu items under:

Edit -> Clear Cell Output

or by using nbstripout

nbstripout /notebook/file

Step 5: Commit Your Changes

Commit your changes with a clear and descriptive commit message:

git add .
git commit -m "Your detailed commit message"

Step 6: Push Changes to Your Fork

Push your changes to your fork on GitHub:

git push origin your-new-branch-name

Step 7: Create a Pull Request

  • Go to the original repository you forked from.
  • Click the Pull request button.
  • Click New pull request.
  • Click compare across forks.
  • Confirm that the base fork is the original repository and the head fork is your fork.
  • Select your branch and click Create pull request.
  • Add a title and description for your pull request.
  • Click Create pull request again to submit.

Step 8: Await Review

After submitting, wait for feedback or review from the project maintainers.

If requested, make further changes and push them to your branch.

Other tools

nbdime

nbdime is useful in tracking changes made to the notebook since the last commit.

If you are making changes to an existing notebook, ensure you use this library to ascertain you are making changes where they are needed.