restructure the contributing guide

[keewis]

From #4355

@max-sixty:

Stepping back on the contributing doc — I admit I haven't look at it in a while — I wonder whether we can slim it down a bit, for example by linking to other docs for generic tooling — I imagine we're unlikely to have the best docs on working with GH, for example. Or referencing our PR template rather than the (now out-of-date) PR checklist.

We could also add a docstring guide since the numpydoc guide does not cover every little detail (for example, default notation, type spec vs. type hint, space before the colon separating parameter names from types, no colon for parameters without types, etc.)

[stale]

In order to maintain a list of currently relevant issues, we mark issues as stale after a period of inactivity

If this issue remains relevant, please comment here or remove the stale label; otherwise it will be marked as closed automatically

[remigathoni]

@keewis What do you think of this structure?

Structure for the Contribution Guide

Overview

• A brief introduction to the community.
• Communication channels
• Where to look for your first issue i.e tags to look out for. For both the code and docs.

Ways to Contribute

• Report a bug
• Request an enhancement
• Contribute to the codebase
• Contribute to the documentation

How to Report a Bug

How to Request an Enhancement

Setting Up the Development Environment

Before contributing to either the docs or the codebase, set up the dev environment.

• Install Anaconda or miniconda
• Fork the repository
• Clone the repository

Contribute to the Codebase

Code standards

• Code formatting
• Backward compatibility

How to contribute to the codebase

• Set up the development environment
  • On Linux
  • On Windows
• Set up the test environment
• Build and install xarray
• Create a feature branch
• Make changes
• Testing
  • Testing with CI
  • Writing tests
  • Using pytest
  • Running the performance test suite
• Documenting your code
• Review your code
• Commit your code
• Submit the pull request
  • PR checklist
• Delete the merged branch

Contribute to the documentation

Documentation comprises of:

• Docstrings
  • Add a numpy docstring guide
• Docs in the xarray/doc folder
  • Uses rst

How to contribute to the documentation

• Set up the docs environment
  • On Linux
  • On Windows
• Build the documentation
• Make changes
• Review your changes
• Submit a pull request

[keewis]

that looks like a good start, thanks.

I wonder if we should change the structure to start with an overview, then link to in-depth guides (just throwing out ideas):

1. project structure

• code
• docs
• packaging (?)
• automation

2. high-level description of a typical workflow (just list the steps and link to relevant documentation):

• setup environment
• create branch
• edit files
• run tests / build docs / run doctests (plus point to CI: for small changes no need to build manually)
• commit
• push to fork
• create PR
• what to do for very short changes (e.g. typo fixes)

3. set up environments (purpose: code including doctests, docs)

• install dependencies (including special things to do for each OS)
• install xarray

4. code standards and conventions
5. tests
6. typing
7. docstring conventions

• format: numpydoc
• examples (doctests)
• see also

9. how to run tests
10. how to build docs
11. how to run doctests
12. special stuff when committing

• pre-commit (and the pre-commit-ci bot)
• commit message tags for controlling CI

13. PR title and message (short section on what to put into the PR description / title)

If that would be easier to follow, we could also split 2) into multiple parts: workflow for code changes (including doctest), workflow for documentation changes. And since we most likely will never be the best source for documentation on general git / github, try to link to other sources like https://docs.github.com or https://git-scm.com

Edit: I guess we could also combine 5 and 9, and 7, 10 and 11

[harshitha1201]

@keewis May I proceed with addressing this issue, based on the structure provided above?

In the OVERVIEW section, we can mention
Overview

link to in-depth guides
->Code of Conduct
->Development Setup
->Code Style
->Testing
->Documentation
->Pull Request Workflow
->Issue Tracker
->Code Contribution Workflow
->Code Review Guidelines
->Release Process
->Developer Documentation
->Communication Channel

[remigathoni]

An overview would make it easier to find sections for sure.
Including what you've mentioned, here's what I have for the overview:

Overview

Project Structure

Prerequisites

• Set up your development environment
  • Linux
  • Windows
• Git workflow
  (Will link to an external resource)

Code

• Suggest a feature
• Report a bug
• Find an issue to work on
• Set up the environment
• Making changes
  • Create branch
  • Edit files
  • Documenting your changes
• Testing
  • Writing tests
  • Running tests (for both the code and the docstrings where necessary )
• Commit your changes
  Links to the section that mentions pre-commit (and the pre-commit-ci bot)
  and commit message tags for controlling CI
• Push to fork
• Create a pull request
• Automated tests
• Backward Compatibility
• Code standards and conventions

Documentation

• Suggest doc improvements

• Find something to work on

  • Making small changes (e.g typo fixes)
  • Check existing GitHub issues
  • Propose a change

• Set up the documentation environment

• Ways to contribute to the documentation

  • User guide
    • Make changes
    • Build docs
  • Docstrings
    • Make changes
    • Docstrings format
      • How to write numpy style docstrings
      • Examples
    • Run doctests

• Create a pull request

PR best practices
(Will link to short section on what to put into the PR description / title)

I have tried to make the contribution workflow for the docs and code as separate as possible which I think makes it easier to follow.