mne-tools / mne-tools/mne-python

Update contributing guide

Open
#11,609 22 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

DOC
Dominant language
Python
Stars
3.5k
Forks
1.6k
Avg merge
1d 6h
Merged PRs (30d)
100

Description

In the last dev meeting, @drammock and I discussed that our Contributing Guide may need an overhaul.

Right now, the guide is long, hard to navigate if you search for something, and hard to understand/follow for new contributors.

The topics discussed (in order) within one page are right now:
ways to contribute, configuring git, GNU make explanation, forking and upstream on GitHub, virtual environments, git commands, SSH with GitHub, documentation, API changes, changelog, local testing, test writing, coding style, naming conventions, docstrings, cross-referencing, code organization, testing, building documentation, MNE command-line tools, GitHub workflow.

While undoubtedly all of this is important, the info is overwhelming and switches between topics (which might make sense, again, if you are following while contributing, but it might be hard to connect the dots when reading this for the first time).

I propose to chop this up into several pages (make it feel less overwhelming, have information on one topic more bundled and use links to interconnect). Further, I propose to potentially have different versions for new contributors and advanced contributors. This could e.g. be realized by having bullet point summaries at the top (if you just need to read up on something you forgot) and then more detailed explanations further down.

TL;DR: Proposal to split the contributor guide into several pages and have sections that speak to the advanced contributor that just wants to look something up as well as sections that are easier to follow and give detailed explanation.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the current Contributing Guide and reviewing how its listed topics are organized. Done means splitting the material into linked pages or sections, with concise summaries and clearer paths for new and advanced contributors.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github, python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.