Contributions page #229

brson · 2015-11-30T21:20:42Z

Based off of @efindlay's original PR, which was based off ncameron's work.

The idea here is to quickly provide the most important links (e.g. the second paragraph reroutes people to bug reporting), subdivide the deluge of information in a way that is digestible (six sections - issue triage, docs, community building, tooling, libs, compiler), then guide people to other sources of information. I've used prose in an attempt to provide context for newbies to understand the larger picture. Sometimes the same information is provided in different sections, from different perspectives - e.g. fixing easy issues vs. writing easy issues.

Ideally, there is an easy path from here to all relevant information for contributors, but that is not quite true yet, and there are types of information that are just not available. What I want this page to do is to link to other, 'living', landing pages for teams, initiatives, topics, etc., and I've tried to do that as much as possible, but there are some categories of information that are not organized anywhere, so sometimes there is more exposition here than I'd like.

This page occasionally links to, and thus endorses, unofficial projects of interest. I want to be clear though that it is not a free-for-all and we are not open to listing arbitrary projects here.

With the quantity and specificity of info here it'll be prone to bitrot and need periodic attendance.

Problems:

The prominent link to 'an overview of the organization, processes, and policies' links somewhere uncomprehensive. I'd like to write this, but there's a lot of info to cover and I want a break from writing for a bit.
Topics of blogging and translation aren't covered.
#rust-libs may not be the right place to direct people who are interested in out-of-tree libs.

I've run out of steam on this and want to get other eyes on it. The libs and tooling sections were the last I hit and it shows.

Although they are very different, my main influence was Scala's page.

Fixes #177.

cc @aturon @steveklabnik

rust-highfive · 2015-11-30T21:20:53Z

r? @alexcrichton

(rust_highfive has picked a reviewer for you, use r? to override)

brson · 2015-11-30T21:25:18Z

This links to the IDEs page, which I have not updated to fit the style of the site. My preference is to move that content to the dungeon/forge.

badboy · 2015-11-30T21:57:10Z

contribute.md

+
+On `E-mentor` issues an experienced Rust developer has volunteered in
+the comments to mentor you through the solving the issue and
+[submitting the fix GitHub pull request][pull]. Contact them about the


This sentence needs fixes. I guess at least the solving the issue and submitting the fix GitHub pull request should be changed.

Wow, what happened...

brson · 2015-11-30T22:08:59Z

An idea I liked but didn't implement, mainly because it would add even more stuff, is to put an 'active initiatives' section near the front, that would link to things like the forum posts for RWIB, Glacier, IDEs, MIR, etc. Curious what others think.

steveklabnik · 2015-11-30T22:49:58Z

contribute.md

+[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta
+[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md
+[rustc-perf]: http://ncameron.org/perf-rustc/
+[rustc-tour]: http://tomlee.co/2014/04/03/a-more-detailed-tour-of-the-rust-compiler/


This post is great, but so old: is it even relevant today?

Maybe not. I'll remove it.

steveklabnik · 2015-11-30T22:50:14Z

👏 👏 👏

nodakai · 2015-11-30T23:06:49Z

Are we required to read through both of the new contributing.html and the existing CONTRIBUTING.md ? I don't think we need both.

nodakai · 2015-11-30T23:22:23Z

contribute.md

+title: Contributing to Rust &middot; The Rust Programming Language
+---
+
+# Contributing to Rust


"Contributing to Rust" carries next to no information. Instead I'd emphasize

There are many ways to contribute to the success of Rust.

because, as I understand it, this document is intended for people who are eager to contribute to Rust but have no idea on where to start.

What might be a more descriptive title?

alexcrichton · 2015-11-30T23:43:59Z

r? @steveklabnik

englishm · 2015-12-01T17:54:47Z

How might people with UX or visual design backgrounds be able to contribute to Rust?

iliekturtles · 2015-12-02T12:57:02Z

contribute.md

+Once you've found your way around the project and have created a few
+pull requests in a particular area, consider reviewing others' pull
+requests: good reviewership is a rare skill and always appreciated. No
+prior permission is needed &emdash; just start constructively and politely


The &emdash; is not rendering properly: search for "emdash" at http://brson.github.io/rust-www/contribute.html

Oops. Should be mdash.

brson · 2015-12-04T22:33:20Z

Are we required to read through both of the new contributing.html and the existing CONTRIBUTING.md ? I don't think we need both.

CONTRIBUTING.md is displayed on new PRs - it catches people who are familiar with the GitHub ecosystem but not the Rust project. It is also specific to the mechanics of contributing to the rust-lang/rust repository. This page is much broader in scope and links to CONTRIBUTING.md as appropriate for the details.

The content is mostly not duplicated, but I think we can trim down CONTRIBUTING.md.

brson · 2015-12-04T22:48:43Z

How might people with UX or visual design backgrounds be able to contribute to Rust?

@englishm Unfortunately, we don't have an answer for this right now. We're hoping to put some planning effort into this area soon so we can give better guidance. If somebody is aware of anything we can tell such people or point them toward that would be productive, I'd be interested.

brson · 2015-12-04T22:51:01Z

I've addressed the current feedback except for @nodakai's concern about the title.

aturon · 2015-12-04T22:57:39Z

I want to give more in-depth feedback, but for now, my biggest concern is that there's just too much here -- that the page is a bit overwhelming.

Can we think of a way to pull out the most juicy bits into a TL;DR section we can stick at the front? I know triage is acting as part of that, but I'm thinking something even tighter.

Note that the Scala site avoids this problem by having all of the sections actually be independent pages. We could consider that as well.

brson · 2015-12-04T23:04:32Z

@aturon Yeah, it's a lot. Do you think that the six areas are a reasonable subdivision?

@bstrie has previously expressed an opinion against subpages.

I'll try reorganizing it so this page is less sprawling, with the bulk of the information elsewhere.

brson · 2015-12-04T23:07:52Z

cc @nrc you may have opinions about this.

aturon · 2015-12-04T23:10:31Z

@brson Yes, I think the structure and content is great. Just hoping we can get something a bit more inviting a la http://scala-lang.org/contribute/

nrc · 2015-12-06T20:06:21Z

+1 for subpages - I think it will help make the page feel less overwhelming. Design-wise, I think having more whitespace and a less dense layout will make this feel better, and that is easier with sub-pages, if the landing page has just a few paras of text and some links, it's easier to space it out.

brson · 2015-12-22T21:18:31Z

OK, I've split each of the 6 subsections into their own pages. See here.

aturon · 2015-12-23T03:59:53Z

@brson Very nice! I feel like that really makes this whole effort come together.

aturon · 2015-12-31T18:24:46Z

One further suggestion: make the links to the subsections stand out a bit -- perhaps bold? There are a lot of links here so emphasizing the primary ones is helpful. (See, again, the Scala page for inspiration here.)

Add link to Manish's new blog post on mentorship. Bolden the contributing subpage links. Remove governance link that goes nowhere.

brson · 2016-01-04T19:10:16Z

I've emboldened the subsection links and also removed the prominent governance link temporarily until we have content for it.

aturon · 2016-01-05T17:12:27Z

@brson: 👍

Btw, are you planning to land these various PRs separately? Or, now that there are cross-cutting style changes, do you want to land them all together?

brson · 2016-01-12T21:14:05Z

@aturon At this point, with the style changes that affect everything I'm planning on landing them together.

brson · 2016-01-12T22:00:51Z

Combined PR.

rust-highfive assigned alexcrichton Nov 30, 2015

brson force-pushed the contributions branch from 8c3532d to d5b89cf Compare November 30, 2015 21:22

badboy reviewed Nov 30, 2015
View reviewed changes

steveklabnik reviewed Nov 30, 2015
View reviewed changes

nodakai reviewed Nov 30, 2015
View reviewed changes

rust-highfive assigned steveklabnik and unassigned alexcrichton Nov 30, 2015

iliekturtles reviewed Dec 2, 2015
View reviewed changes

brson force-pushed the contributions branch from d95698b to aa38474 Compare December 22, 2015 20:54

Eric Findlay and others added 3 commits December 22, 2015 20:54

Added contribution page

c5b06de

Added "Getting Started" to contribution.md

8fb7d95

Various changes to contributions.html

47ba377

brson added 5 commits December 22, 2015 20:54

Add contributing to navbar

0eb30fa

Massively expand the contributing page

def9c2a

Link the developers to the github contribution page, not AUTHORS.txt

87c9ee0

Address feedback on contributing page

5d372c8

Add *~ to .gitignore

c9c8f02

brson force-pushed the contributions branch from aa38474 to 1bb607f Compare December 22, 2015 20:57

Break contribution page into subpages

1bb607f

brson mentioned this pull request Dec 23, 2015

Add a documentation page. Restructure navigation #241

Closed

Few tweaks

79f1c1f

Add link to Manish's new blog post on mentorship. Bolden the contributing subpage links. Remove governance link that goes nowhere.

brson mentioned this pull request Jan 12, 2016

New doc, contribution, and FAQ pages #244

Merged

brson closed this Jan 12, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributions page #229

Contributions page #229

brson commented Nov 30, 2015

rust-highfive commented Nov 30, 2015

brson commented Nov 30, 2015

badboy Nov 30, 2015

brson Dec 4, 2015

brson commented Nov 30, 2015

steveklabnik Nov 30, 2015

brson Dec 4, 2015

steveklabnik commented Nov 30, 2015

nodakai commented Nov 30, 2015

nodakai Nov 30, 2015

brson Dec 4, 2015

alexcrichton commented Nov 30, 2015

englishm commented Dec 1, 2015

iliekturtles Dec 2, 2015

brson Dec 4, 2015

brson commented Dec 4, 2015

brson commented Dec 4, 2015

brson commented Dec 4, 2015

aturon commented Dec 4, 2015

brson commented Dec 4, 2015

brson commented Dec 4, 2015

aturon commented Dec 4, 2015

nrc commented Dec 6, 2015

brson commented Dec 22, 2015

aturon commented Dec 23, 2015

aturon commented Dec 31, 2015

brson commented Jan 4, 2016

aturon commented Jan 5, 2016

brson commented Jan 12, 2016

brson commented Jan 12, 2016

Contributions page #229

Contributions page #229

Conversation

brson commented Nov 30, 2015

rust-highfive commented Nov 30, 2015

brson commented Nov 30, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brson commented Nov 30, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Nov 30, 2015

nodakai commented Nov 30, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexcrichton commented Nov 30, 2015

englishm commented Dec 1, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brson commented Dec 4, 2015

brson commented Dec 4, 2015

brson commented Dec 4, 2015

aturon commented Dec 4, 2015

brson commented Dec 4, 2015

brson commented Dec 4, 2015

aturon commented Dec 4, 2015

nrc commented Dec 6, 2015

brson commented Dec 22, 2015

aturon commented Dec 23, 2015

aturon commented Dec 31, 2015

brson commented Jan 4, 2016

aturon commented Jan 5, 2016

brson commented Jan 12, 2016

brson commented Jan 12, 2016