Closed
Description
Git is a major part of contributing to rust-lang/rust, but it sees almost no discussion in the guide. There should be instructions on:
- How to pull, branch, push, etc. This can just be a link to a git tutorial, but it should be there. It should also have basic instructions on GitHub (even if it's just 'the create pull request button is here').
- How to rebase. A lot of people are afraid of rebasing if they haven't used it a lot: the commands are not intuitive, it's rewriting history which already sounds scary, and you run into merge conflicts as you go which make the whole thing even more painful. There should be a detailed walkthrough on this.
- The no-merges policy. This is really discouraging to newcomers: they have a change that works, but it's not accepted because of what seems like paperwork. It should say why we have this policy and how to fix your PR if you made a merge by accident.
Writing this requires no knowledge of rust or the compiler (although having made PRs to rust-lang/rust is a bonus). It should go in the 'Contributing to Rust' section, possibly in its own page.
Metadata
Metadata
Assignees
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Activity
jyn514 commentedon Sep 6, 2020
Possibly there should be instructions on how to do this in a GUI too, but I've never used a git gui for rebasing and I wouldn't be able to help with that bit.
workingjubilee commentedon Sep 6, 2020
People should be reminded that making a branch is effectively free in git, so it's fine to just pop over to another branch to save their workstate and then pop back. I cheat by just reaching back in history through the reflog if I screw up but... who even has heard of the reflog?
jyn514 commentedon Sep 6, 2020
'Git tips' would also be a useful section (maybe near
git worktree
in the suggested workflows page?) but I see it as something separate from this issue, which is 'how do I contribute at all'.We should mention how to fix issues from adding a submodule by accident though: rust-lang/rust#75949 (comment)
Maybe we should also suggest
git add <file>
instead ofgit add .
? That would help prevent committing submodules in the first place.workingjubilee commentedon Sep 6, 2020
Right, I mean that as a heads-up before rebasing. "rebasing sounds intimidating but you can make an additional branch, push it to your fork on GH or whatever, and guaranteed you have your work saved."
Yeah, people should be adding by-file, or at least by-specific-directory, in a deliberate fashion, not
git add .
.workingjubilee commentedon Sep 6, 2020
Graphical Git UIs are always going to be a case-by-case for each, so covering rebasing in any of them will require someone who actually has used that tool, or finding other people's tutorials. However, many people lean on VS Code as a dev tool, and since VS Code is semi-officially-supported by rust-analyzer, so we should probably lean on assisting people with VS Code's support for git, as a start.
spastorino commentedon Sep 7, 2020
Niko showed https://devguide.python.org/ to me and found that there are some things about git there. Maybe we can use some inspiration from their devguide :)
jyn514 commentedon Sep 7, 2020
Hmm, that's mostly just branching - I'd like to cover rebasing in more depth. It's a good start though :)
spastorino commentedon Sep 7, 2020
Yeah I didn't carefully look at it, I was just guessing that there may be some good content there :). Still something that may inspire some of our things in the guide :).
jyn514 commentedon Sep 9, 2020
Another good section would be how to squash commits (related to #824, but with less setup preferably).
guswynn commentedon Sep 10, 2020
I found https://rustc-dev-guide.rust-lang.org/building/suggested.html#working-on-multiple-branches-at-the-same-time to be extremely valuable, adding more stuff about git usage would be great! (also, I know somewhere in the guide it talks about the style around squashed vs unsquashed commits, but reiterating that in a dedicated git section would be awesome)
jyn514 commentedon Sep 10, 2020
In the meantime, @GuillaumeGomez has a great blog post about this here: https://blog.guillaume-gomez.fr/Git-tips/1/1
GuillaumeGomez commentedon Sep 11, 2020
@jyn514 If you talk about squashing commits, it's https://blog.guillaume-gomez.fr/Git-tips/1/2 ;) (and thanks for linking to it!)
Although I wrote those tutorials mostly for rust contributors so I guess all chapters are applicable.
camelid commentedon Sep 11, 2020
Yeah, VS Code has decent interactive support for resolving merge conflicts.
19 remaining items