New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add initial contributor and style guide #307

Merged
merged 4 commits into from May 4, 2017

Conversation

Projects
None yet
4 participants
@ddbeck
Contributor

ddbeck commented Apr 30, 2017

This PR adds a contributing and style guide started on the develop branch (with a few edits). Based on the discussion with @jonparrott from #301, this is the first step in retiring the develop branch. Some of this doc is based on conventions that I've seen elsewhere in the guide, other bits are aspirational (e.g., headings use different styles in different places, so I tried to aim for easier to explain and maintain). I'm happy to make any changes needed to get this into mergeable state.

@ncoghlan

ncoghlan approved these changes May 1, 2017 edited

This generally looks good to me - just one substantive comment regarding the exact wording of the guide's purpose.

What's currently there isn't wrong, but I suspect it may confuse some readers due to the whole "distributions" vs "Python distributions" vs "distribution packages" ambiguity problem.

The purpose of the |PyPUG| is

to be the authoritative resource on how to package, publish and install
Python distributions using current tools

This comment has been minimized.

@ncoghlan

ncoghlan May 1, 2017

Member

We conceded the "distributions" terminology debate a while back, so I'd suggest rephrasing this to:

to be the authoritative resource on how to define, build, publish, and install Python distribution packages using current tools

That rephrasing also avoids the ambiguity with Python distributions like ActivePython, EPD/Canopy, Anaconda/miniconda, pyenv, Linux packages, Mac homebrew, etc

I also considered reordering the subactivities in order of the number of people that engage in them, from most common (installing packages published by others) to least common (publishing your own packages), but that phrasing was much more awkward than using the chronological order of the publishing process. Instead, I just split "package" into two subtasks ("define" and "build") so it wasn't be used as both a noun and a verb in the same sentence.

This comment has been minimized.

@pfmoore

pfmoore May 1, 2017

Member

In this instance, I'd be inclined to use the term "Python projects" in place of "Python distribution packages". At this point, the reader can be assumed to have a limited feel for the subtleties of technical terms like "distribution package", and "project", while ambiguous, probably corresponds most closely with the reader's intuitive understanding.

This comment has been minimized.

@ncoghlan

ncoghlan May 1, 2017

Member

+1 for "Python projects", which would give:

to be the authoritative resource on how to package, publish, and install Python projects using current tools

(since "package" should be in there somewhere, and with the noun form removed the sentence, we're free to use it as a verb again)

This comment has been minimized.

@ddbeck

ddbeck May 1, 2017

Contributor

I was quoting source/index.rst here. Should I update this text in both places?

This comment has been minimized.

@theacodes

theacodes May 1, 2017

Member

I'd say go ahead. :)

This comment has been minimized.

@ncoghlan

ncoghlan May 2, 2017

Member

Yep, update it in both - the current phrasing presumably dates from when we were still trying to disambiguate distribution packages from import packages by introducing a different term rather than just qualifying "package" as needed.

and tone. Does it sound like something you would say or does it sound like
you're acting out a part or giving a speech? Feel free to use contractions and
don't worry about sticking to fussy grammar rules. You are hereby granted
permission to end a sentence in a preposition.

This comment has been minimized.

@ncoghlan

ncoghlan May 1, 2017

Member

I tried to figure out how to rephrase this sentence so it ended in a preposition, but no such luck :)

This comment has been minimized.

@pfmoore

pfmoore May 1, 2017

Member

"You are hereby granted permission to end a sentence in a preposition, if that's what you want to end it with." :-) Sorry, couldn't resist.

This comment has been minimized.

@ddbeck

ddbeck May 1, 2017

Contributor

YES! Seriously, I spent entirely too much time trying to come up with something like that.

This comment has been minimized.

@ncoghlan

ncoghlan May 1, 2017

Member

Excellent!


**Use a gender-neutral style**
Often, you'll address the reader directly with *you*, *your* and *yours*.
Otherwise, user gender-neutral pronouns *they*, *their*, and *theirs* or

This comment has been minimized.

@ncoghlan

ncoghlan May 1, 2017

Member

s/user/use/

Daniel D. Beck added some commits May 1, 2017

@ncoghlan ncoghlan merged commit f0d34a5 into pypa:master May 4, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@ncoghlan

This comment has been minimized.

Member

ncoghlan commented May 4, 2017

And done! Thanks @ddbeck :)

ncoghlan added a commit to ncoghlan/python-packaging-user-guide that referenced this pull request Jun 24, 2017

Add initial contributor and style guide (pypa#307)
* adds an initial contributor and style guide
* importantly, ends a sentence in a preposition (@pfmoore succeeded where others had failed)
* updates the guide's purpose statement to better reflect common terminology
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment