From ezio.melotti at gmail.com Fri Sep 8 14:53:38 2017 From: ezio.melotti at gmail.com (Ezio Melotti) Date: Fri, 8 Sep 2017 21:53:38 +0300 Subject: [core-workflow] Devguide Reorganization Message-ID: As you might have noticed, during the sprint I've been mostly working on reorganizing the devguide. The bulk of the changes I made affect the following pages: 1. setup.rst: setup instructions that should be done only once, targeted to everybody 2. pullrequest.rst: instructions about creating pull requests, targeted to everybody 3. committing.rst: instructions about accepting/merging PRs, targeted to core devs These three pages cover all the steps from installing git to getting a PR merged with upstream. The first two apply to contributors and core devs alike, whereas the third is for core devs only. Unlike most of the other pages in the devguide, these three pages are process-oriented, and consist in a sequence of steps that should be read from start to finish. People can easily skip steps as they see fit (e.g. they can skip "installing git" if they already have it installed). I also want to make clear in the index.rst page that "reading the devguide" -- a currently unfeasible task for most -- should only mean reading these two pages (three for core devs). These pages will contain links to the other "informational" pages -- those should be consulted when the need arises and should not be a prerequisite reading. Some of the changes I made have already been merged, some are waiting for review, and there are several more that I'm planning to do. Some of the goals and design principles I'm following are: * make the devguide easier to read and navigate; * remove duplication and overly verbose sections -- prefer bullet lists and to-the-point prose; * when multiple options are available, document the one that works for most cases; possibly add a footnote or link to a separate section with alternative approaches; * make information easier to find with ctrl+f, especially in FAQ-like pages; * prefer few longer pages than many small pages; * most pages should have an introduction that explains what can you find in the page and the target audience, followed by a concise overview/summary/ToCs (should fit in 1 screen), with links to other sections/pages that cover the topics in more detail; Special thanks to Victor, Mariatta, and Carol for the valuable feedback provided during the sprint and on the PRs! Best Regards, Ezio Melotti -------------- next part -------------- An HTML attachment was scrubbed... URL: From brett at python.org Mon Sep 18 19:02:31 2017 From: brett at python.org (Brett Cannon) Date: Mon, 18 Sep 2017 23:02:31 +0000 Subject: [core-workflow] Devguide Reorganization In-Reply-To: References: Message-ID: I haven't looked at the results of this work but it all sounds great! Thanks to everyone who worked on this! I really appreciate and support the shift towards "getting things done"-focused docs in the devguide where lower-level details get shifted in an appendix section that people can reference as necessary/desired. That should definitely make the whole devguide less intimidating and easier to digest for those who come to it for the first time without losing relevant reference sections. On Fri, 8 Sep 2017 at 11:53 Ezio Melotti wrote: > As you might have noticed, during the sprint I've been mostly working on > reorganizing the devguide. The bulk of the changes I made affect the > following pages: > 1. setup.rst: setup instructions that should be done only once, targeted > to everybody > 2. pullrequest.rst: instructions about creating pull requests, targeted to > everybody > 3. committing.rst: instructions about accepting/merging PRs, targeted to > core devs > > These three pages cover all the steps from installing git to getting a PR > merged with upstream. The first two apply to contributors and core devs > alike, whereas the third is for core devs only. > > Unlike most of the other pages in the devguide, these three pages are > process-oriented, and consist in a sequence of steps that should be read > from start to finish. People can easily skip steps as they see fit (e.g. > they can skip "installing git" if they already have it installed). > > I also want to make clear in the index.rst page that "reading the > devguide" -- a currently unfeasible task for most -- should only mean > reading these two pages (three for core devs). > > These pages will contain links to the other "informational" pages -- those > should be consulted when the need arises and should not be a prerequisite > reading. > > > Some of the changes I made have already been merged, some are waiting for > review, and there are several more that I'm planning to do. Some of the > goals and design principles I'm following are: > * make the devguide easier to read and navigate; > * remove duplication and overly verbose sections -- prefer bullet lists > and to-the-point prose; > * when multiple options are available, document the one that works for > most cases; possibly add a footnote or link to a separate section with > alternative approaches; > * make information easier to find with ctrl+f, especially in FAQ-like > pages; > * prefer few longer pages than many small pages; > * most pages should have an introduction that explains what can you find > in the page and the target audience, followed by a concise > overview/summary/ToCs (should fit in 1 screen), with links to other > sections/pages that cover the topics in more detail; > > Special thanks to Victor, Mariatta, and Carol for the valuable feedback > provided during the sprint and on the PRs! > > Best Regards, > Ezio Melotti > _______________________________________________ > core-workflow mailing list > core-workflow at python.org > https://mail.python.org/mailman/listinfo/core-workflow > This list is governed by the PSF Code of Conduct: > https://www.python.org/psf/codeofconduct > -------------- next part -------------- An HTML attachment was scrubbed... URL: From ezio.melotti at gmail.com Wed Sep 20 00:54:17 2017 From: ezio.melotti at gmail.com (Ezio Melotti) Date: Wed, 20 Sep 2017 07:54:17 +0300 Subject: [core-workflow] Devguide Reorganization In-Reply-To: References: Message-ID: On Tue, Sep 19, 2017 at 2:02 AM, Brett Cannon wrote: > I haven't looked at the results of this work but it all sounds great! > https://github.com/python/devguide/pull/263 and a few other minor PRs are already merged, but there is still a major one waiting for review: https://github.com/python/devguide/pull/265 In the past few days I've been working on updating the bug tracker, so I haven't worked on the devguide. I plan on picking that up again once I'm done with the tracker. By the time you are back from your month off there should be more PRs waiting for review :) > Thanks to everyone who worked on this! I really appreciate and support the > shift towards "getting things done"-focused docs in the devguide where > lower-level details get shifted in an appendix section that people can > reference as necessary/desired. That should definitely make the whole > devguide less intimidating and easier to digest for those who come to it > for the first time without losing relevant reference sections. > > On Fri, 8 Sep 2017 at 11:53 Ezio Melotti wrote: > >> As you might have noticed, during the sprint I've been mostly working on >> reorganizing the devguide. The bulk of the changes I made affect the >> following pages: >> 1. setup.rst: setup instructions that should be done only once, targeted >> to everybody >> 2. pullrequest.rst: instructions about creating pull requests, targeted >> to everybody >> 3. committing.rst: instructions about accepting/merging PRs, targeted to >> core devs >> >> These three pages cover all the steps from installing git to getting a PR >> merged with upstream. The first two apply to contributors and core devs >> alike, whereas the third is for core devs only. >> >> Unlike most of the other pages in the devguide, these three pages are >> process-oriented, and consist in a sequence of steps that should be read >> from start to finish. People can easily skip steps as they see fit (e.g. >> they can skip "installing git" if they already have it installed). >> >> I also want to make clear in the index.rst page that "reading the >> devguide" -- a currently unfeasible task for most -- should only mean >> reading these two pages (three for core devs). >> >> These pages will contain links to the other "informational" pages -- >> those should be consulted when the need arises and should not be a >> prerequisite reading. >> >> >> Some of the changes I made have already been merged, some are waiting for >> review, and there are several more that I'm planning to do. Some of the >> goals and design principles I'm following are: >> * make the devguide easier to read and navigate; >> * remove duplication and overly verbose sections -- prefer bullet lists >> and to-the-point prose; >> * when multiple options are available, document the one that works for >> most cases; possibly add a footnote or link to a separate section with >> alternative approaches; >> * make information easier to find with ctrl+f, especially in FAQ-like >> pages; >> * prefer few longer pages than many small pages; >> * most pages should have an introduction that explains what can you find >> in the page and the target audience, followed by a concise >> overview/summary/ToCs (should fit in 1 screen), with links to other >> sections/pages that cover the topics in more detail; >> >> Special thanks to Victor, Mariatta, and Carol for the valuable feedback >> provided during the sprint and on the PRs! >> >> Best Regards, >> Ezio Melotti >> _______________________________________________ >> core-workflow mailing list >> core-workflow at python.org >> https://mail.python.org/mailman/listinfo/core-workflow >> This list is governed by the PSF Code of Conduct: >> https://www.python.org/psf/codeofconduct >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From rodrigc at crodrigues.org Wed Sep 20 13:58:57 2017 From: rodrigc at crodrigues.org (Craig Rodrigues) Date: Wed, 20 Sep 2017 10:58:57 -0700 Subject: [core-workflow] Moving to Buildbot 9 and Python 3 Message-ID: I initiated discussion about moving python.org to using Buildbot 9 and Python 3: https://mail.python.org/pipermail/python-buildbots/2017-September/000133.html Folks involved with core-workflow may want to monitor that thread, because I believe it has implications on core developer workflow for Python. Luckily, I think the implications are good. :) Some of the implications I can think of include: - buildbot 9 runs on Python 3, whereas the current buildbot 8 does not (and never will) - buildbot 9 exposes a REST API with queryable endpoints - buildbot 9 has better integration with GitHub pull requests, as can be seen here: http://nine.buildbot.net/#/console - buildbot 9 has better support for Docker, and providers who work with containers such as Hyper.sh -- Craig -------------- next part -------------- An HTML attachment was scrubbed... URL: From brett at python.org Thu Sep 21 12:21:32 2017 From: brett at python.org (Brett Cannon) Date: Thu, 21 Sep 2017 16:21:32 +0000 Subject: [core-workflow] Moving to Buildbot 9 and Python 3 In-Reply-To: References: Message-ID: Thanks for the heads-up, Craig! The REST API might be nice to have and the provider support may be rather useful in increasing OS configuration coverage or guaranteed slave stability if the PSF was willing to pay for some machine time. On Wed, 20 Sep 2017 at 10:59 Craig Rodrigues wrote: > I initiated discussion about moving python.org to using Buildbot 9 > and Python 3: > https://mail.python.org/pipermail/python-buildbots/2017-September/000133.html > > Folks involved with core-workflow may want to monitor that thread, because > I believe it has implications on core developer workflow for Python. > Luckily, I think the implications are good. :) > > Some of the implications I can think of include: > > - buildbot 9 runs on Python 3, whereas the current buildbot 8 does not > (and never will) > - buildbot 9 exposes a REST API with queryable endpoints > - buildbot 9 has better integration with GitHub pull requests, as can be > seen here: > http://nine.buildbot.net/#/console > - buildbot 9 has better support for Docker, and providers who work with > containers such as Hyper.sh > > -- > Craig > _______________________________________________ > core-workflow mailing list > core-workflow at python.org > https://mail.python.org/mailman/listinfo/core-workflow > This list is governed by the PSF Code of Conduct: > https://www.python.org/psf/codeofconduct > -------------- next part -------------- An HTML attachment was scrubbed... URL: