iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Some gramatical fixes and slight rewordings

This commit is contained in:
Donald Stufft 2014-11-29 19:21:23 -05:00
parent 3a5e2bdbfb
commit 5f0c213e23
1 changed files with 57 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
pep-0481.txt
View File

@ -41,23 +41,22 @@ do not typically have complex workflows or often branches at all other than the
primary integration branch. This simplicity makes them very good targets for primary integration branch. This simplicity makes them very good targets for
the "Pull Request" workflow that is commonly found on sites like Github. the "Pull Request" workflow that is commonly found on sites like Github.
However where PEP 474 wants to continue to use Mercurial and wishes to use an However whereas PEP 474 proposes to continue to use Mercurial and restricts
OSS and self-hosted and therefore restricts itself to only those solutions this itself to only solutions which are OSS and self-hosted, this PEP expands the
PEP expands the scope of that to include migrating to Git and using Github. scope of that to include migrating to Git and using Github.
The existing method of contributing to these repositories generally includes The existing method of contributing to these repositories generally includes
generating a patch and either uploading them to bugs.python.org or emailing generating a patch and either uploading them to bugs.python.org or emailing
them to peps@python.org. This process is unfriendly towards non-comitter them to peps@python.org. This process is unfriendly towards non-comitter
contributors as well as making the process harder than it needs to be for contributors as well as cumbersome for comitters seeking to accept the patches
comitters to accept the patches sent by users. In addition to the benefits sent by users. In contrast, the Pull Request workflow style enables non
in the pull request workflow itself, this style of workflow also enables techincal contributors, especially those who do not know their way around the
non techincal contributors, especially those who do not know their way around DVCS of choice, to contribute using the web based editor. On the committer
the DVCS of choice, to contribute using the web based editor. On the committer side, the Pull Requests enable them to tell, before merging, whether or not
side the Pull Requests enable them to tell, before merging, whether or not
a particular Pull Request will break anything. It also enables them to do a a particular Pull Request will break anything. It also enables them to do a
simple "push button" merge which does not require them to check out the simple "push button" merge which does not require them to check out the
changes locally. Another such feature that is useful in particular for docs, changes locally. Another such feature that is useful in particular for docs,
is the ability to view a "prose" diff. This Github specific feature enables is the ability to view a "prose" diff. This Github-specific feature enables
a committer to view a diff of the rendered output which will hide things like a committer to view a diff of the rendered output which will hide things like
reformatting a paragraph and show you what the actual "meat" of the change reformatting a paragraph and show you what the actual "meat" of the change
actually is. actually is.
@ -66,15 +65,14 @@ actually is.
Why Git? Why Git?
-------- --------
Looking at the variety of DVCS which are available today it becomes fairly Looking at the variety of DVCS which are available today, it becomes fairly
clear that git has gotten the vast mindshare of people who are currently using clear that git has the largest mindshare. The Open Hub (Previously Ohloh)
it. The Open Hub (Previously Ohloh) statistics [#openhub-stats]_ show that statistics [#openhub-stats]_ show that currently 37% of the repositories
currently 37% of the repositories Open Hub is indexing is using git which is indexed by Open Hub are using git which is second only to SVN (which has 48%),
second only to SVN (which has 48%) while Mercurial has just 2% of the indexed while Mercurial has just 2% of the indexed repositories (beating only bazaar
repositories (beating only bazaar which has 1%). In additon to the Open Hub which has 1%). In additon to the Open Hub statistics, a look at the top 100
statistics a look at the top 100 projects on PyPI (ordered by total download projects on PyPI (ordered by total download counts) shows that within the
counts) shows us that within the Python space itself there is a majority of Python space itself, the majority of projects use git.
projects using git:
=== ========= ========== ====== === ==== === ========= ========== ====== === ====
Git Mercurial Subversion Bazaar CVS None Git Mercurial Subversion Bazaar CVS None
@ -85,49 +83,47 @@ Git Mercurial Subversion Bazaar CVS None
Chosing a DVCS which has the larger mindshare will make it more likely that any Chosing a DVCS which has the larger mindshare will make it more likely that any
particular person who has experience with DVCS at all will be able to particular person who has experience with DVCS at all will be able to
meaningfully use the DVCS that we have chosen without having to learn a new meaningfully contribute without having to learn a new tool.
tool.
In addition to simply making it more likely that any individual will already In addition to simply making it more likely that any individual will already
know how to use git, the number of projects and people using it means that the know how to use git, the number of projects and people using it means that the
resources for learning the tool are likely to be more fully fleshed out and resources for learning the tool are likely to be more fully fleshed out.
when you run into problems the liklihood that someone else had that problem When you run into problems, the liklihood that someone else had that problem
and posted a question and recieved an answer is also far likelier. and posted a question and recieved an answer is also far likelier.
Thirdly by using a more popular tool you also increase your options for tooling Thirdly, by using a more popular tool you also increase your options for
*around* the DVCS itself. Looking at the various options for hosting tooling *around* the DVCS itself. Looking at the various options for hosting
repositories it's extremely rare to find a hosting solution (whether OSS or repositories, it's extremely rare to find a hosting solution (whether OSS or
commerical) that supports Mercurial but does not support Git, on the flip side commerical) that supports Mercurial but does not support Git. On the flip side,
there are a number of tools which support Git but do not support Mercurial. there are a number of tools which support Git but do not support Mercurial.
Therefore the popularity of git increases the flexibility of our options going Therefore the popularity of git increases the flexibility of our options going
into the future for what toolchain these projects use. into the future for what toolchain these projects use.
Also by moving to the more popular DVCS we increase the likelhood that the Also, by moving to the more popular DVCS, we increase the likelhood that the
knowledge that the person has learned in contributing to these support knowledge that the person has learned in contributing to these support
repositories will transfer to projects outside of the immediate CPython project repositories will transfer to projects outside of the immediate CPython project
such as to the larger Python community which is primarily using Git hosted on such as to the larger Python community which is primarily using Git hosted on
Github. Github.
In previous years there was concern about how well supported git was on Windows In previous years there was concern about how well supported git was on Windows
in comparison to Mercurial. However git has grown to support Windows as a first in comparison to Mercurial. However, git has grown to support Windows as a
class citizen. In addition to that, for Windows users who are not well aquanted first class citizen. In addition to that, for Windows users who are not well
with the Windows command line there are GUI options as well. aquanted with the Windows command line, there are GUI options as well.
On a techincal level git and Mercurial are fairly similar, however the git On a techincal level git and Mercurial are fairly similar, however the git
branching model is signifcantly better than Mercurial "Named Branches" for branching model is signifcantly better than Mercurial "Named Branches" for
non-comitter contributors. Mercurial does have a "Bookmarks" extension however non-comitter contributors. Mercurial does have a "Bookmarks" extension, however
this isn't quite as good as git's branching model. All bookmarks live in the this isn't quite as good as git's branching model. All bookmarks live in the
same namespace so it requires individual users to ensure that they namespace same namespace so it requires individual users to ensure that they namespace
the branchnames themselves lest the risk collision. It also is an extension the branchnames themselves lest the risk collision. It also is an extension
which requires new users to first discover they need an extension at all and which requires new users to first discover they need an extension at all, and
then figure out what they need to do in order to enable that extension. Since then figure out what they need to do in order to enable that extension. Since,
it is an extension it also means that in general support for them outside of in contrast to the branching feature in git, this feature is a Mercurial
Mercurial core is going to be less than 100% in comparison to git where the extension, in general, its support outside the Mercurial core is less
feature is built in and core to using git at all. Finally users who are not extensive. Finally, users who are not used to Mercurial are unlikely to
used to Mercurial are unlikely to discover bookmarks on their own, instead they discover bookmarks on their own, instead they will likely attempt to use
will likely attempt to use Mercurial's "Named Branches" which, given the fact Mercurial's "Named Branches" which, given the fact they live "forever", are not
they live "forever", are not often what a project wants their contributors to often what a project wants their contributors to use.
use.
Why Github? Why Github?
@ -142,8 +138,8 @@ There are two primary reasons for selecting Github: Popularity and
Quality/Polish. Quality/Polish.
Github is currently the most popular hosted repository hosting according to Github is currently the most popular hosted repository hosting according to
Alexa where it currently has a global rank of 121. Much like for Git itself by Alexa, where it currently has a global rank of 121. Much like for Git itself,
choosing the most popular tool we gain benefits in increasing the likelhood by choosing the most popular tool we gain benefits in increasing the likelhood
that a new contributor will have already experienced the toolchain, the quality that a new contributor will have already experienced the toolchain, the quality
and availablity of the help, more and better tooling being built around it, and and availablity of the help, more and better tooling being built around it, and
the knowledge transfer to other projects. A look again at the top 100 projects the knowledge transfer to other projects. A look again at the top 100 projects
@ -162,7 +158,7 @@ far more polished. This is hard to quantify objectively however it is a fairly
common sentiment if you go around and ask people who are using these services common sentiment if you go around and ask people who are using these services
often. often.
Finally a reason to choose a web service at all over something that is Finally, a reason to choose a web service at all over something that is
self-hosted is to be able to more efficiently use volunteer time and donated self-hosted is to be able to more efficiently use volunteer time and donated
resources. Every additional service hosted on the PSF infrastruture by the resources. Every additional service hosted on the PSF infrastruture by the
PSF infrastructure team further spreads out the amount of time that the PSF infrastructure team further spreads out the amount of time that the
@ -175,7 +171,7 @@ lack of control and that at some point in the future the service may no longer
be suitable. It is the opinion of this PEP that Github does not currently and be suitable. It is the opinion of this PEP that Github does not currently and
has not in the past engaged in any attempts to lock people into their platform has not in the past engaged in any attempts to lock people into their platform
and that if at some point in the future Github is no longer suitable for one and that if at some point in the future Github is no longer suitable for one
reason or another than at that point we can look at migrating away from Github reason or another, then at that point we can look at migrating away from Github
onto a different solution. In other words, we'll cross that bridge if and when onto a different solution. In other words, we'll cross that bridge if and when
we come to it. we come to it.
@ -188,24 +184,25 @@ of a DVCS, the repository hosting, and the workflow used is the social network
and size of the community using said tools. We can see this is true by looking and size of the community using said tools. We can see this is true by looking
at an example from a sub-community of the Python community: The Scientific at an example from a sub-community of the Python community: The Scientific
Python community. They have already migrated most of the key pieces of the Python community. They have already migrated most of the key pieces of the
SciPy stack onto Github using the Pull Request based workflow starting with SciPy stack onto Github using the Pull Request based workflow. This process
IPython and as more projects moved over it became a natural default for new started with IPython, and as more projects moved over it became a natural
projects. default for new projects in the community.
They claim to have seen a great benefit from this move, where it enables casual They claim to have seen a great benefit from this move, in that it enables
contributors to easily move between different projects within their casual contributors to easily move between different projects within their
sub-community without having to learn a special, bespoke workflow and a sub-community without having to learn a special, bespoke workflow and a
different toolchain for each project. They've found that when people can use different toolchain for each project. They've found that when people can use
their limited time on actually contributing instead of learning the different their limited time on actually contributing instead of learning the different
tools and workflows that not only do they contribute more to one project, that tools and workflows that, not only do they contribute more to one project, but
they also expand out and contribute to other projects. This move is also that they also expand out and contribute to other projects. This move has also
attributed to making it commonplace for members of that community to go so far been attributed to the increased tendency for members of that community to go
as publishing their research and educational materials on Github as well. so far as publishing their research and educational materials on Github as
well.
This showcases the real power behind moving to a highly popular toolchain and This example showcases the real power behind moving to a highly popular
workflow, as each variance introduces yet another hurdle for new and casual toolchain and workflow, as each variance introduces yet another hurdle for new
contributors to get past and it makes the time spent learning that workflow and casual contributors to get past and it makes the time spent learning that
less reusable with other projects. workflow less reusable with other projects.
Migration Migration
@ -214,7 +211,7 @@ Migration
Through the use of hg-git [#hg-git]_ we can easily convert a Mercurial Through the use of hg-git [#hg-git]_ we can easily convert a Mercurial
repository to a Git repository by simply pushing the Mercurial repository to repository to a Git repository by simply pushing the Mercurial repository to
the Git repository. People who wish to continue to use Mercurual locally can the Git repository. People who wish to continue to use Mercurual locally can
then use hg-git going into the future using the new Github URL, however they then use hg-git going into the future using the new Github URL. However they
will need to re-clone their repositories as using Git as the server seems to will need to re-clone their repositories as using Git as the server seems to
trigger a one time change of the changeset ids. trigger a one time change of the changeset ids.
@ -222,7 +219,7 @@ As none of the selected repositories have any tags, branches, or bookmarks
other than the ``default`` branch the migration will simply map the ``default`` other than the ``default`` branch the migration will simply map the ``default``
branch in Mercurial to the ``master`` branch in git. branch in Mercurial to the ``master`` branch in git.
In addition since none of the selected projects have any great need of a In addition, since none of the selected projects have any great need of a
complex bug tracker, they will also migrate their issue handling to using the complex bug tracker, they will also migrate their issue handling to using the
GitHub issues. GitHub issues.