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.

@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

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

@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

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