Skip to content

Latest commit

 

History

History
96 lines (60 loc) · 4.26 KB

CONTRIBUTION.md

File metadata and controls

96 lines (60 loc) · 4.26 KB
Raw

Contribution Guidelines

Follow this guide to start contributing to the ERC handbook

Setting up

  • Fork the repository to your github account by pressing the 'Fork' button on the top right corner of the screen when you open the repo

  • Clone your fork to your computer using :

    git clone https://github.com/your-github-username/handbook.git

  • Set the remotes :

    git remote add origin https://www.github.com/your-github-username/handbook.git
git remote add upstream https://www.github.com/ERC-BPGC/handbook.git

  • Updating the forks:

    git fetch upstream

  • Installing dependencies:

    python3 -m pip install -r requirements.txt

Ways of Contributing

1. Openning new issues

You can open issues from the issues page of the repo. Issues can be opened if you:

  • Have ideas for new things that can be added to the handbook

  • Find any errors / mistakes in handbook

  • General suggestion on how the handbook can be improved

2. Solving Issues

You can start working on an unsolved issue by requesting to take it up in the Issues Section of the repo on github. The issue will then be assigned to it and you are good to go.

After the issue is assigned to you, you can start working on it by setting up a local repo by following the steps giving in the configuration section.

Remember to update your local repo before starting the work everytime by using :

git pull upstream master

At this stage you will be ready to make your changes.

Modifying the handbook

We are using the mkdocs-material theme of mkdocs to build the handbook. The documentations of both tools have many details regarding further configuration etc.

All the documentation is written in the form of markdown files which are contained within the /docs/ directory and are sorted according to the field of robotics that the content of the file pertains to. For ways to do cool things with markdown like callouts, tables, emojis etc. check out this page.

We are using Python Markdown's Arithmatex extention for rendering mathjax (this includes latex) for which you can find more details here.

Adding a new page to the handbook involves two steps -

  1. Create the .md file for the page in the relevant section.
  2. Modify the nav section of mkdocs.yml to contain a reference to the name of the new file. As an example, if you want to add content to the Getting started with ROS subsection of the ROS sub-section of Automation, the nav segement will look something like this :
nav :
  - Automation :
    - Introduction:path/to/intro.md
    - ROS :
      - Getting Started with ROS:path/to/getting_started.md

To check how your page looks when built, you can run mkdocs serve from the root directory of the project. The cool thing is the page will autoupdate as you make changes to the .md source file.

Once you feel your addition is ready, you should stage and commit your changes and push to your fork.

git add .
git commit -m "Added stuff"
git push

After this all you have to do is open a pull request. While opening a pull request please make sure that the title of your PR is of the form [DD/MM/YY] Nice framed message describing the changes. Here, we have set up an automated test to see if the docs in the PR build, so make sure your contribution passes that.

One of the team will review your PR, suggest any changes if requires and finally merge your contribution to the master branch of the handbook.

Since, we are using a GitHub Action to deploy the docs, whenever there are any updates to the master branch, the website will be automatically updated.