Skip to content

Reorganizing the contribution guide

Jump to bottom
Joannah Nanjekye edited this page Jun 12, 2022 · 3 revisions

Author: Joannah Nanjekye

Introduction

The contributing guide is the face documentation for any open source project contributors. The goal for the re-organization is to:

  • Add any missing sections making it holistic
  • Elaborate existing sections with more relevant contribution detail

This outline proposes the main sections of the new contributors guide.

Proposed Documentation Structure

We are using the Diátaxis documentation structure. The structure dictates that the documentation is divided into four main parts; Getting started, How-to guides, Reference, and Explanation. The structure gives a clear scope and sets a clear tone on where each piece of information should go, for both users and documentation authors.

The contributor guide is currently a separate section outside these major categories. In future it may make sense to put it under the Getting Started section. The main sections for the contribution guide are listed below:

  • Getting started for developers
    • Installation
    • Using Geomstats
      • Instantiate a manifold
      • Instantiate an algorithm
      • Run the algorithm
  • Development Setup
    • Source control with Git
    • Getting the source code
      • Forking the repository
      • Pulling the code
    • Dependencies
    • Choosing a Backend
    • Run the tests
    • Build the docs
    • Debugging
  • Folder structure
    • geomstats
    • docs
    • examples
    • Notebooks
    • tests
  • Testing
    • What is TDD
    • TDD with pytest
    • Writing tests for Geomstats
    • Running tests
      • The whole test suite
      • A single test file
      • A test case
    • Running the benchmarks
  • Documentation
    • Introduction to RST
    • Categories
    • Guidelines and best practices
    • Testing
    • Docstrings style guide
  • Coding style
    • PEP 8
    • code style guidelines i.e., classes, methods, variable etc
    • Black formatter
  • Workflow of a contribution
    • Create or choose an issue
    • Create a new branch
    • Making changes
    • Run tests
    • commit and push
    • Review
    • Merge
    • Pull request checklist
    • Deleting merged branch
  • Reporting bugs and features
    • Issue tracker
    • Template of a bug/issue report
  • Issue Triaging
    • Reproducing issues
    • Commenting on alternative solutions
    • Answering questions
    • Labelling and assigning the issue
Clone this wiki locally