Moving this to an issue for public feedback @LPereira95 @ninamiolane
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
Moving this to an issue for public feedback @LPereira95 @ninamiolane
Introduction
The contributing guide is the face documentation for any open source project contributors. The goal for the re-organization is to:
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: