[Python-Dev] Statistics of documentation changes
For the discussion about translating Python documentation I have collected some statistics. See the attachment. The difference of the documentation between recent feature releases is only 5-7%. Early bugfix releases change about 1-2% of the documentation. The tutorial is more stable. There is only 2% difference between recent releases. Early bugfix releases change about 1% of the tutorial. Doc/ changes: total: 557 files changed, 238295 insertions(+), 43 deletions(-) 3.2 -> 3.3: 324 files changed, 30040 insertions(+), 10043 deletions(-) 3.3 -> 3.4: 390 files changed, 29534 insertions(+), 10609 deletions(-) 3.4 -> 3.5: 407 files changed, 16543 insertions(+), 7020 deletions(-) 3.5 -> 3.6: 186 files changed, 10966 insertions(+), 3564 deletions(-) v2.7 -> v2.7.1: 165 files changed, 3295 insertions(+), 1578 deletions(-) v2.7.1 -> v2.7.2: 113 files changed, 6418 insertions(+), 5082 deletions(-) v2.7.2 -> v2.7.3: 312 files changed, 7191 insertions(+), 6729 deletions(-) v2.7.3 -> v2.7.4: 263 files changed, 5128 insertions(+), 2979 deletions(-) v2.7.4 -> v2.7.5: 59 files changed, 1039 insertions(+), 1144 deletions(-) v2.7.5 -> v2.7.6: 144 files changed, 2183 insertions(+), 1556 deletions(-) v2.7.6 -> v2.7.7: 108 files changed, 1348 insertions(+), 856 deletions(-) v2.7.7 -> v2.7.8: 33 files changed, 413 insertions(+), 115 deletions(-) v2.7.8 -> v2.7.9: 168 files changed, 5464 insertions(+), 3623 deletions(-) v2.7.9 -> v2.7.10: 59 files changed, 1591 insertions(+), 1199 deletions(-) v2.7.10 -> v2.7.11: 88 files changed, 810 insertions(+), 480 deletions(-) v2.7.11 -> v2.7.12: 198 files changed, 2420 insertions(+), 1744 deletions(-) v2.7.12 -> v2.7.13: 168 files changed, 1199 insertions(+), 778 deletions(-) v3.2 -> v3.2.1: 114 files changed, 1987 insertions(+), 1500 deletions(-) v3.2.1 -> v3.2.2: 81 files changed, 871 insertions(+), 562 deletions(-) v3.2.2 -> v3.2.3: 155 files changed, 2473 insertions(+), 3859 deletions(-) v3.2.3 -> v3.2.4: 219 files changed, 6427 insertions(+), 3319 deletions(-) v3.2.4 -> v3.2.5: v3.2.5 -> v3.2.6: 7 files changed, 89 insertions(+), 27 deletions(-) v3.3.0 -> v3.3.1: 204 files changed, 5196 insertions(+), 3645 deletions(-) v3.3.1 -> v3.3.2: 93 files changed, 1632 insertions(+), 1514 deletions(-) v3.3.2 -> v3.3.3: 184 files changed, 3339 insertions(+), 2507 deletions(-) v3.3.3 -> v3.3.4: 105 files changed, 1249 insertions(+), 583 deletions(-) v3.3.4 -> v3.3.5: 34 files changed, 323 insertions(+), 240 deletions(-) v3.3.5 -> v3.3.6: 34 files changed, 477 insertions(+), 502 deletions(-) v3.4.0 -> v3.4.1: 81 files changed, 1039 insertions(+), 772 deletions(-) v3.4.1 -> v3.4.2: 94 files changed, 2723 insertions(+), 1130 deletions(-) v3.4.2 -> v3.4.3: 220 files changed, 6152 insertions(+), 5526 deletions(-) v3.4.3 -> v3.4.4: 208 files changed, 3091 insertions(+), 1833 deletions(-) v3.4.4 -> v3.4.5: 16 files changed, 108 insertions(+), 114 deletions(-) v3.4.5 -> v3.4.6: 4 files changed, 28 insertions(+), 4 deletions(-) v3.5.0 -> v3.5.1: 143 files changed, 2337 insertions(+), 1196 deletions(-) v3.5.1 -> v3.5.2: 348 files changed, 4170 insertions(+), 3548 deletions(-) v3.5.2 -> v3.5.3: 223 files changed, 2838 insertions(+), 1761 deletions(-) Doc/tutorial/ changes: total: 17 files changed, 6145 insertions(+) 3.2 -> 3.3: 10 files changed, 516 insertions(+), 565 deletions(-) 3.3 -> 3.4: 15 files changed, 549 insertions(+), 348 deletions(-) 3.4 -> 3.5: 14 files changed, 150 insertions(+), 170 deletions(-) 3.5 -> 3.6: 9 files changed, 122 insertions(+), 101 deletions(-) v2.7 -> v2.7.1: 6 files changed, 123 insertions(+), 103 deletions(-) v2.7.1 -> v2.7.2: 5 files changed, 34 insertions(+), 40 deletions(-) v2.7.2 -> v2.7.3: 8 files changed, 218 insertions(+), 122 deletions(-) v2.7.3 -> v2.7.4: 11 files changed, 169 insertions(+), 98 deletions(-) v2.7.4 -> v2.7.5: 2 files changed, 8 insertions(+), 18 deletions(-) v2.7.5 -> v2.7.6: 7 files changed, 64 insertions(+), 54 deletions(-) v2.7.6 -> v2.7.7: 2 files changed, 52 insertions(+), 35 deletions(-) v2.7.7 -> v2.7.8: 2 files changed, 83 insertions(+), 2 deletions(-) v2.7.8 -> v2.7.9: 8 files changed, 413 insertions(+), 418 deletions(-) v2.7.9 -> v2.7.10: 3 files changed, 8 insertions(+), 6 deletions(-) v2.7.10 -> v2.7.11: 3 files changed, 13 insertions(+), 13 deletions(-) v2.7.11 -> v2.7.12: 12 files changed, 32 insertions(+), 25 deletions(-) v2.7.12 -> v2.7.13: 5 files changed, 22 insertions(+), 16 deletions(-) v3.2 -> v3.2.1: 5 files changed, 61 insertions(+), 39 deletions(-) v3.2.1 -> v3.2.2: 4 files changed, 44 insertions(+), 18 deletions(-) v3.2.2 -> v3.2.3: 7 files changed, 152 insertions(+), 120 deletions(-) v3.2.3 -> v3.2.4: 12 files changed, 195 insertions(+), 105 deletions(-) v3.2.4 -> v3.2.5: v3.2.5 -> v3.2.6: v3.3.0 -> v3.3.1: 12 files changed, 165 insertions(+), 100 deletions(-) v3.3.1 -> v3.3.2: 2 files changed, 8 insertions(+), 18 deletions(-) v3.3.2 -> v3
Re: [Python-Dev] Translated Python documentation
On Fri, 24 Feb 2017 at 03:50 INADA Naoki wrote: > > Where should these translated docs live and how does one make it clear to > > users reading them that doc bugs shouldn't be submitted to the main bug > > tracker/github repo? > > > > We setup github page. See https://python-doc-ja.github.io/py36/ (note > that > version switcher won't work because this html is build for docs.python.jp > .) > > I reserved "python-docs" organization. So we can use URL like > https://python-doc.github.io//3.6/ > (Because the organization name looks "something official", I won't use it > until we get consensus about it.) > > For issue tracker, bugs.html must mention about translated document, before > mention to normal issue tracker. > It's getting a little hard to tease out what exactly is being asked at this point. Perhaps it's time to move the discussion over to a translation SIG (which probably needs to be created unless the old https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way active translators can figure out exactly what they want to ask of python-dev in terms of support and we can have a more focused discussion. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Translated Python documentation
On Feb 25, 2017, at 13:19, Brett Cannon wrote: > It's getting a little hard to tease out what exactly is being asked at this > point. Perhaps it's time to move the discussion over to a translation SIG > (which probably needs to be created unless the old > https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way > active translators can figure out exactly what they want to ask of python-dev > in terms of support and we can have a more focused discussion. I agree. We would need a more concrete and detailed proposal to really make any thoughtful decision. That may also include getting approval from the PSF Board as they are ultimately responsible for the contents of python.org. Without more detail, I don't have an opinion myself other than to note that, if we do something, it needs to be careful to not complicate or restrict the Python release process. -- Ned Deily n...@python.org -- [] ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Translated Python documentation
Yes, right place to discussion is one of important things what I want. I haven't know about i18n-sig. Is it better than docs-sig? Another thing I want is agreement to use project name looks like (semi)official project. We used "python-doc-jp" name on Transifex at first. But since some people other than Japanese ask me to allow other languages, I renamed it to "python-doc". And I reserved "python-docs" organization at Github. While it's better name for working together with other Language translators, I don't like that unofficial project use such name. Hosting at docs.python.org is desirable too, but it can be discussed later. Regards, On Sun, Feb 26, 2017 at 4:08 AM, Ned Deily wrote: > On Feb 25, 2017, at 13:19, Brett Cannon wrote: >> It's getting a little hard to tease out what exactly is being asked at this >> point. Perhaps it's time to move the discussion over to a translation SIG >> (which probably needs to be created unless the old >> https://mail.python.org/mailman/listinfo/i18n-sig makes sense)? That way >> active translators can figure out exactly what they want to ask of >> python-dev in terms of support and we can have a more focused discussion. > > I agree. We would need a more concrete and detailed proposal to really make > any thoughtful decision. That may also include getting approval from the PSF > Board as they are ultimately responsible for the contents of python.org. > Without more detail, I don't have an opinion myself other than to note that, > if we do something, it needs to be careful to not complicate or restrict the > Python release process. > > -- > Ned Deily > n...@python.org -- [] > > ___ > Python-Dev mailing list > Python-Dev@python.org > https://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > https://mail.python.org/mailman/options/python-dev/songofacandy%40gmail.com ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Split Misc/NEWS into individual files
On Feb 24, 2017, at 11:40 PM, Larry Hastings wrote: >I'm for it too. Fixing up Misc/NEWS is probably the trickiest and most >error-prone part of cutting a release. Not to mention cherry picking for older releases. >While I'm sure we can learn a lot by examining "reno", my suspicion is we'll >want our own custom tool. I don't think the hard part is writing the >tool--the hard part is figuring out what we want and how it should be >integrated into our workflow. Actually writing such a tool is easy and fun, >and I'm sure our community would fall all over themselves to write it if >asked. In fact, I'll kind of pre-volunteer to write it right now, as long as >I can write it in Python 3 ;-) What else would you write it in?! :) Let's start with a simple question: do we like the general layout of the existing Misc/NEWS file? I do, and I *really* like it containing issue numbers, because that makes it relatively easy to search to see if a particular bug was fixed in a particular version (which is also why I wish all pull requests were tied to a bug). Other things I like about the file: * It's easy to search for a particular Python release, just by searching for "What's New". * I like having a release date easily visible with the Python version heading. * I like the bullet list format of the file, and I like the alphabetized category headings. What I don't like: * Lines that are too long ;) * All the inherent conflicts in editing a single file. * Misc/NEWS (on master) doesn't go back farther than 2 Python versions and 2 years, so it's harder to search for earlier changes. * It's in Misc/ not Doc/ Can we agree then that Misc/NEWS is the target output format for this tool? Maybe it's not the *only* target output format? Now, what's the input? The other thing is that I'm not sure design-by-committee is going to work so well here. There are several competing interests here. Release managers, non-core devs (drive-by contributors needing sponsorship), core devs (back porting/cherry picking changes), downstream consumers. Cheers, -Barry ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Split Misc/NEWS into individual files
On Wed, 22 Feb 2017 at 13:30 Ned Deily wrote: > On Feb 22, 2017, at 07:27, Victor Stinner > wrote: > > > [...]My idea is not new, it's already discussed in the Python > core-workflow: > > https://github.com/python/core-workflow/issues/6 > > > > I'm opening a thread on python-dev because Misc/NEWS quickly became a > > blocker issue with the Python new workflow. > > > > What do you think of the overall idea? > > I think we clearly need to do something about Misc/NEWS but this issue is > already under discussion in the core-workflow working group and I think we > shouldn't be moving it to python-dev until there is a final concrete > proposal. I know it is high on Brett's list but I believe he's taking a > few days of holiday right so he may not be able to respond immediately. > Let's move this discussion over to the core-workflow mailing list. It can > wait a few days. > > https://mail.python.org/mailman/listinfo/core-workflow Ned is right that I was on holiday for the past week and am slowly digging myself out from underneath my pile of email. Ned is also right that I view the Misc/NEWS issue the most important thing to solve next for our workflow as we have been putting up with merge conflicts on this file for long enough. Since this is going to be a somewhat protracted discussion as there are multiple tools consider (including writing our own), I think we should keep the discussion at https://github.com/python/core-workflow/issues/6. ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Split Misc/NEWS into individual files
tools, projects, changelog filenames x-posting from https://github.com/python/core-workflow/issues/6#issuecomment-282529194 : ... changelog filenames - CHANGELOG.rst - HISTORY.rst - whatsnew.rst - Misc/NEWS ### ``Escaping M``arkup NOTE: commit logs may contain (executable) markup - **https://wiki.python.org/moin/EscapingHtml** - https://github.com/westurner/dotfiles/blob/develop/scripts/git-changelog.py - ``rst_escape()`` (!?) Tools - mergenews - Src: https://bitbucket.org/larry/mergenews - splitnews - mergenews - pyci - hg-specific - Reno - Src: https://github.com/openstack/reno - Src: https://github.com/openstack/reno/blob/master/reno/formatter.py - Src: https://github.com/openstack/reno/blob/master/reno/sphinxext.py - PyPI: https://pypi.org/project/reno - Docs: https://docs.openstack.org/developer/reno/usage.html#editing-a-release-note - [x] ENH: "make sections configurable" https://github.com/openstack/reno/commit/081a4145e18c82acba877ee22c180b3428c773f6 - Towncrier - Src: https://github.com/hawkowl/towncrier - PyPI: https://pypi.org/project/towncrier Projects: - CPython - https://github.com/python/cpython/blob/master/Misc/NEWS - IPython - https://github.com/ipython/ipython/tree/master/docs/source/whatsnew/pr#documenting-whats-new - https://github.com/ipython/ipython/tree/master/docs/source/whatsnew - Src: https://github.com/ipython/ipython/blob/master/tools/update_whatsnew.py - Matplotlib - https://github.com/matplotlib/matplotlib/blob/master/doc/users/whats_new.rst - https://github.com/matplotlib/matplotlib/tree/master/doc/users/prev_whats_new - https://github.com/matplotlib/matplotlib/tree/master/doc/users/whats_new README.rst - scikit-learn - ENH, BUG, DOC, MRG - https://github.com/scikit-learn/scikit-learn/blob/master/doc/whats_new.rst - statsmodels - ENH, BUG, DOC, MRG - https://github.com/statsmodels/statsmodels/tree/master/docs/source/release - OpenStack Nova - reno - https://git.openstack.org/cgit/openstack/nova/tree/releasenotes/notes - https://github.com/openstack/nova/tree/master/releasenotes/notes - http://lists.openstack.org/pipermail/release-announce/2017-February/000784.html On Sat, Feb 25, 2017 at 1:10 PM, Brett Cannon wrote: > > > On Wed, 22 Feb 2017 at 13:30 Ned Deily wrote: > >> On Feb 22, 2017, at 07:27, Victor Stinner >> wrote: >> >> > [...]My idea is not new, it's already discussed in the Python >> core-workflow: >> > https://github.com/python/core-workflow/issues/6 >> > >> > I'm opening a thread on python-dev because Misc/NEWS quickly became a >> > blocker issue with the Python new workflow. >> > >> > What do you think of the overall idea? >> >> I think we clearly need to do something about Misc/NEWS but this issue is >> already under discussion in the core-workflow working group and I think we >> shouldn't be moving it to python-dev until there is a final concrete >> proposal. I know it is high on Brett's list but I believe he's taking a >> few days of holiday right so he may not be able to respond immediately. >> Let's move this discussion over to the core-workflow mailing list. It can >> wait a few days. >> >> https://mail.python.org/mailman/listinfo/core-workflow > > > Ned is right that I was on holiday for the past week and am slowly digging > myself out from underneath my pile of email. > > Ned is also right that I view the Misc/NEWS issue the most important thing > to solve next for our workflow as we have been putting up with merge > conflicts on this file for long enough. > > Since this is going to be a somewhat protracted discussion as there are > multiple tools consider (including writing our own), I think we should keep > the discussion at https://github.com/python/core-workflow/issues/6. > > ___ > Python-Dev mailing list > Python-Dev@python.org > https://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: https://mail.python.org/mailman/options/python-dev/ > wes.turner%40gmail.com > > ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Translated Python documentation
On 26 February 2017 at 05:57, INADA Naoki wrote: > Yes, right place to discussion is one of important things what I want. > I haven't know about i18n-sig. Is it better than docs-sig? > > > Another thing I want is agreement to use project name looks like > (semi)official project. > > We used "python-doc-jp" name on Transifex at first. But since some people > other than Japanese ask me to allow other languages, I renamed it to > "python-doc". > And I reserved "python-docs" organization at Github. > +1 from me for continuing to use those names (although you may want to standardise on "python-docs", since the mailing list is docs-sig, and the site is docs.python.org). While it's not translation related, I'll also note an idea that came up at the language summit a couple of years ago: moving the tutorial and the howto guides *out* of the version-specific documentation and into a separate version independent docs repository. As the stats Serhiy posted suggest, these typically *don't* change a great deal between versions, and when they do, the version differences are often going to be better handled inline (e.g. "On versions older than 3.x, ") rather than by maintaining multiple distinct versions of the document. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Handling PR branches in "make patchcheck"
Hi folks, With the move to a PR based workflow, I've been finding "make patchcheck" less helpful than it used to be, as it was only checking the changes that had yet to be committed at all, and ignoring those that had already been checked in on the PR branch. I've put together a proposed update to Tools/scripts/patchcheck.py that makes it aware of git branches, and automatically diffs against the base branch when it detects something that "looks like" a PR branch: http://bugs.python.org/issue29656 I can vouch for it working in my particular setup (where "origin" refers to the upstream repo), but it would be good if folks could try it out with other configurations before we merge it (in particular, it *should* handle the case where the upstream remote is called "upstream", but I don't use that arrangement myself). Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
