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.

Sign up for GitHub

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

Jump to bottom

Could CONTRIBUTING.md be improved? #77215

Closed
mightyiam opened this issue Sep 26, 2020 · 6 comments · Fixed by #82887
Closed

Could CONTRIBUTING.md be improved? #77215

mightyiam opened this issue Sep 26, 2020 · 6 comments · Fixed by #82887
Assignees
@henryboisdequin
Labels
A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one.

Comments

@mightyiam
Copy link
Contributor

mightyiam commented Sep 26, 2020 •
edited by rustbot
Loading

The CONTRIBUTING.md, writes:

Contributing to Rust

Thank you for your interest in contributing to Rust!

To get started, read the [Getting Started] guide in the [rustc-dev-guide].

Perhaps it could be a little better. What throws me off in this last sentence, is the term rustc. I'm just a total newbie and just getting to know the terms in this language, so there's no surprise that I can't explain why I am sent one place or another for documentation. So, this is more of a question to those familiar with the constellation of terms, repositories, web sites, and so on. Could this reference explain why it refers to rustc-dev-guide and not anything else. I want to contribute to documentation of what seems to be a core macro (#77100). So, I'm not sure that reading the "Guide to Rustc Development" would be the correct thing to do (even thought I will surely personally read it at some point). The readme of this repository writes:

This is the main source code repository for Rust. It contains the compiler, standard library, and documentation.

So, in the CONTRIBUTING.md file, I expect to be directed to instructions on contributing to all or any of the compiler, standard library and documentation. But I am directed to what seems to be — at least by title alone (I haven't read into it, yet) — solely about contributing to the rust compiler.

Any suggestion regarding how to improve this — I have the intention of implementing myself. By the way, I am streaming my contribution to rust live at https://twitch.tv/mightyiam.
@mightyiam mightyiam added the C-bug Category: This is a bug. label Sep 26, 2020
@pickfire
Copy link
Contributor

I personally think CONTRIBUTING.md should still redirect to rustc-dev-guide but I think the guide could be improved. IIRC the guide was not updated regarding the split of compiler, library and core. The guide talks more about contributing to the rust compiler, but personally I think contributing to the library should be straightforward besides not knowing how to build a custom toolchain which isn't always necessary. @mightyiam I believe you can just create a pull request for this if you see fit to close the issue (so it doesn't hang around and become lost).

@follower
Copy link
Contributor

@mightyiam Yeah, I've very recently run into a similar issue; based on my research, it seems the original content of CONTRIBUTING.md now lives at https://rustc-dev-guide.rust-lang.org/contributing.html which seems like a better entry point.

It seems the contribution/developer docs are currently mid-transition from one approach to a new one.

Related:

@LeSeulArtichaut LeSeulArtichaut added A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself C-enhancement Category: An issue proposing an enhancement or a PR with one. and removed C-bug Category: This is a bug. labels Sep 27, 2020
@LeSeulArtichaut
Copy link
Contributor

cc @rust-lang/wg-rustc-dev-guide

@jyn514 jyn514 added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Sep 27, 2020
@follower follower mentioned this issue Sep 27, 2020
Merged
@follower
Copy link
Contributor

follower commented Sep 27, 2020 •
edited
Loading

Having just discovered that the GitHub "first issue" pop-up also links to this document, I just went ahead & created PR #77268 which links to the chapter of the dev guide that now holds the content that was previously in CONTRIBUTING.md.

rust-first-issue-github-popup-screenshot

Until the "Getting Started" chapter gets re-written to be less rustc-specific, linking to it rather than "Contributing to Rust" chapter seems unnecessarily unwelcoming to new contributors, particularly those who were specifically directed there while creating an issue.

(Of course, if the "first issue" link can be customised that's another option for the future.)

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Oct 22, 2020
@Dylan-DPC
Rollup merge of rust-lang#77268 - follower:patch-3, r=jyn514
ff817fa 
Link to "Contributing to Rust" rather than "Getting Started".

Change to link to "Contributing to Rust" chapter of `rustc` Dev Guide, primarily on the basis that:

 * The GitHub "first contribution" Issue "pop-up" says "Be sure to review the [contributing guidelines] and [code of conduct]" and links to this file.

 * The "Bug Report" section _seems_ to restrict itself to if "a compiler error message [told] you to come here".

 * The previous content of `CONTRIBUTING.md` now lives in the "Contributing to Rust" chapter.

When/if the guide/"Getting Started" section gets revised to not be `rustc`-specific, the choice of linked chapter could be updated.

In the meantime this prevents leading first time contributors into a confusing cul de sac.

_[I wasn't planning to make a PR for this until discussion in rust-lang#77215 concluded but the discovery that the "first issue" pop-up also links to this document IMO makes it a higher priority to make the link useful sooner rather than later.]_

Related issues:

 * rust-lang#77215

 * rust-lang/rustc-dev-guide#775 (comment)
JohnTitor added a commit to JohnTitor/rust that referenced this issue Oct 23, 2020
@JohnTitor
Rollup merge of rust-lang#77268 - follower:patch-3, r=jyn514
b40ca64 
Link to "Contributing to Rust" rather than "Getting Started".

Change to link to "Contributing to Rust" chapter of `rustc` Dev Guide, primarily on the basis that:

 * The GitHub "first contribution" Issue "pop-up" says "Be sure to review the [contributing guidelines] and [code of conduct]" and links to this file.

 * The "Bug Report" section _seems_ to restrict itself to if "a compiler error message [told] you to come here".

 * The previous content of `CONTRIBUTING.md` now lives in the "Contributing to Rust" chapter.

When/if the guide/"Getting Started" section gets revised to not be `rustc`-specific, the choice of linked chapter could be updated.

In the meantime this prevents leading first time contributors into a confusing cul de sac.

_[I wasn't planning to make a PR for this until discussion in rust-lang#77215 concluded but the discovery that the "first issue" pop-up also links to this document IMO makes it a higher priority to make the link useful sooner rather than later.]_

Related issues:

 * rust-lang#77215

 * rust-lang/rustc-dev-guide#775 (comment)
@henryboisdequin
Copy link
Contributor

@rustbot claim

@henryboisdequin henryboisdequin mentioned this issue Mar 8, 2021
Merged
m-ou-se added a commit to m-ou-se/rust that referenced this issue Mar 9, 2021
@m-ou-se
Rollup merge of rust-lang#82887 - henryboisdequin:improve-contributin…
07d5de3 
…g-md, r=joshtriplett

Update CONTRIBUTING.md

Fixes rust-lang#77215

As mentioned in rust-lang#77215, the current CONTRIBUTING.md links to the rustc-dev-guide.
Even though the rustc-dev-guide has lots of useful information for contributors,
one is already confused by reading the first line of the current CONTRIBUTING.md.

> To get started, read the [Getting Started] guide in the [rustc-dev-guide].

This line tells the contributor to go and read the rustc-dev-guide. What is
the rustc-dev-guide? What does rustc even mean? These are some of the
questions that went into my head when reading this line as a first-time
contributor. By explaining what the rustc-dev-guide is and some platforms
to get help, a new contributor understands what the first step is and the process
is much clearer. The `About the [rustc-dev-guide]` section explains what
the rustc-dev-guide is, what rustc is, and the purpose out of reading the
guide. The `Getting help` section points the user to some places where
they can get help, find a mentor, and introduce themselves.
m-ou-se added a commit to m-ou-se/rust that referenced this issue Mar 9, 2021
@m-ou-se
Rollup merge of rust-lang#82887 - henryboisdequin:improve-contributin…
74de9db 
…g-md, r=joshtriplett

Update CONTRIBUTING.md

Fixes rust-lang#77215

As mentioned in rust-lang#77215, the current CONTRIBUTING.md links to the rustc-dev-guide.
Even though the rustc-dev-guide has lots of useful information for contributors,
one is already confused by reading the first line of the current CONTRIBUTING.md.

> To get started, read the [Getting Started] guide in the [rustc-dev-guide].

This line tells the contributor to go and read the rustc-dev-guide. What is
the rustc-dev-guide? What does rustc even mean? These are some of the
questions that went into my head when reading this line as a first-time
contributor. By explaining what the rustc-dev-guide is and some platforms
to get help, a new contributor understands what the first step is and the process
is much clearer. The `About the [rustc-dev-guide]` section explains what
the rustc-dev-guide is, what rustc is, and the purpose out of reading the
guide. The `Getting help` section points the user to some places where
they can get help, find a mentor, and introduce themselves.
@bors bors closed this as completed in 469c030 Mar 9, 2021
@mightyiam
Copy link
Contributor Author

Thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@henryboisdequin henryboisdequin

Labels
A-contributor-roadblock Area: Makes things more difficult for new contributors to rust itself A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Update CONTRIBUTING.md henryboisdequin/rust
6 participants
@follower @mightyiam @pickfire @jyn514 @LeSeulArtichaut @henryboisdequin