Repository navigation
Simplify the index page by audience #189
Description
Activity
I think the core dev section may also need to be split, although I'm not sure what the two sub-audiences should be called. The way I think of them:
- Professional software developer: your day job specifically involves writing software to meet the needs of someone other than yourself. As part of that work, you're already familiar with automated testing, reviewing code changes, discussing design trade-offs, and deciding the appropriate scope of particular projects.
- Domain expert: your primary interest & expertise lies in an area other than professional software development (e.g. computer science education, general education, journalism, legal practice, economics, scientific research, data analysis, system operations & administration, systems engineering). Contributing to CPython accounts for the bulk of your experience with the practices & processes involved in developing software as part of a larger team working on a code base that's too large for any one person to comprehensively understand.
For the first group, the key things to highlight are those points that relate to collaborating with self-motivated volunteers rather than working solely with full-time colleagues as part of a paid development team. Most importantly: don't assume everyone else working on the project is a professional software developer.
For the second group, we may need to be more explicit about things we'd consider "foundational knowledge you should already have learned at work" for a professional software dev (such as how to use a code review tool as a reviewer, or the right terms to use to search for things on Google).
Thank you for identifying the two groups and suggesting that the second group, which includes me, should not necessarily by empty.
Agreed - I'd put myself in the second group too. Even though I'm technically a developer, in practical terms the processes used in my line of work are so different from those used in open source that it may as well be a different profession. (Although I've worked enough in open source that the tools are familiar, the processes are most decidedly not).
I'd also point out that for group 2 we should also include reminders that many core devs are in group 1 - which means that they may not even understand the difficulties you're having with the tools and processes, so work with them accordingly.
Attempting a more value-neutral description of the two categories:
- Procedurally aligned profession: the processes and practices you use in your day job are well-aligned with those used in the CPython project (for example, working for an open source redistributor, working as an independent contractor building open source based systems, or working for a large organisation with clearly defined policies for open source participation). As a result of that, you're already familiar with concepts and techniques like automated testing, reviewing code changes, discussing design trade-offs, coaching other contributors, and deciding the appropriate scope of particular projects.
- Independent activity: your primary interest & expertise lies in an area that doesn't regularly incorporate the kinds of processes and practices used in the CPython project (e.g. software development in small co-located teams, systems engineering, computer science education, general education, journalism, legal practice, economics, scientific research, data analysis, system operations & administration). Contributing to CPython accounts for the bulk of your experience with the concepts & techniques involved in developing software as part of a distributed team working in the open on a code base that's too large for any one person to comprehensively understand.
With that reworded explanation, I would have been in the "Independent Activity" category when I was still at Boeing, and only considered myself part of the "Procedurally aligned profession" category after moving to Red Hat in 2011.
Reacted by DimitrisJimIOW "software development as a job" and "software development for fun" 😉 .
Not quite, as folks in the second category may still develop software as their day job (just with radically different practices & processes - that was the case for me when I was at Boeing), while folks in the first category may still be participating in CPython development out of purely personal interest.
Reacted by nonameOnce we do this I think it will help show redundancies that have accumulated over time (e.g. all the git information that we have spread out across the devguide).
I'm looking into this as part of #120. The 3 main places where the git info are are:
- https://devguide.python.org/gitbootcamp/#gitbootcamp
- https://devguide.python.org/committing/#working-with-git
- https://docs.python.org/devguide/pullrequest.html#quick-guide-step-by-step
I'm currently thinking about leaving 1 alone (its faq nature doesn't even require separating between contributors and committers), getting rid of 2 (moving relevant parts either in 1 or 3), and keep 3 as a process-oriented section that includes the basic commands and refers to 1 for more advances use cases.
3 could be target mostly to contributors (the workflow they follow is similar to ours) and possibly include a follow-up section with committers-specific instructions for merging (but that shouldn't include any git command).Reacted by MariattaI made some changes in #263 and #265.
- New contributors
a. New to open source (e.g. needs help to build Python)
b. Just new to the project (i.e. just needs to know how the project does things - Core devs
- Appendix
I don't think this is necessary. Since the workflow is now mostly the same for contributors and core devs, the only core-devs-specific information should be in the committing.rst page. The distinction between new to open source and new to the project is also not necessary: the devguide describes all the steps, if people already have git installed or have already built Python, they can just skip those steps.
Once we do this I think it will help show redundancies that have accumulated over time (e.g. all the git information that we have spread out across the devguide).
I already took care of this in #263 -- all the git information are now in 3 places:
- setup instructions in setup.rst (you need this only once)
- PR-lifecycle-related commands (creating branches, committing, pushing, etc) in pullrequest.rst
- misc commands, special cases, etc in gitbootcamp.rst
In #265 I also removed most duplication between the pullrequest.rst and committing.rst pages.
- New contributors
A different distinction I want to make is:
- process-oriented pages that you should read:
- setup.rst for initial setup
- pullrequest.rst for instructions about the PR-based workflow
- (for core devs only) committing.rst for instructions about accepting/merging PRs
- additional pages that you should consult once the need arises
See also the "Devguide Reorganization" thread on core-workflow.
- process-oriented pages that you should read:
This is completed by the addition of the table by contributor type.
The index page has become rather long and is starting to feel like a wall of text. It should probably be clearly separated into 3 sections:
a. New to open source (e.g. needs help to build Python)
b. Just new to the project (i.e. just needs to know how the project does things
Once we do this I think it will help show redundancies that have accumulated over time (e.g. all the git information that we have spread out across the devguide).