Skip to content
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

ddbeck
Copy link
Contributor

@ddbeck 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.

Copy link
Member

@ncoghlan ncoghlan left a comment

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
Copy link
Member

@ncoghlan ncoghlan May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@pfmoore pfmoore May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@ncoghlan ncoghlan May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+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)

Copy link
Contributor Author

@ddbeck ddbeck May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@theacodes theacodes May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say go ahead. :)

Copy link
Member

@ncoghlan ncoghlan May 2, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Member

@ncoghlan ncoghlan May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@pfmoore pfmoore May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.

Copy link
Contributor Author

@ddbeck ddbeck May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@ncoghlan ncoghlan May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

@ncoghlan ncoghlan May 1, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/user/use/

@ncoghlan ncoghlan merged commit f0d34a5 into pypa:master May 4, 2017
1 check passed
@ncoghlan
Copy link
Member

ncoghlan commented May 4, 2017

And done! Thanks @ddbeck :)

ncoghlan pushed a commit to ncoghlan/python-packaging-user-guide that referenced this issue Jun 24, 2017
* 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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants