Clarify the meaning of remote commands. #26
Conversation
You are only ever talking to your local copy of the remote, except for the new command I added an example of, so I tried to make that clear. Also fixed a nit with switching branches: you *must* run make afterward (at least you do if you expect to test anything). And added a reference to git worktree...I'm fine if that gets rejected; I haven't used it yet myself :)
| @@ -243,6 +243,7 @@ Simply use ``git checkout`` to checkout another branch in the current directory: | |||
| $ git branch | |||
| master | |||
| * 3.5 | |||
| $ make | |||
There was a problem hiding this comment.
I mentioned that in the commit message. You can't do any testing unless you run make after switching branches. If you forget the make, weird and mysterious things may happen.
There was a problem hiding this comment.
@bitdancer It's likely more user friendly to separate out the make command to a separate paragraph.
Perhaps:
Simply use ``git checkout`` to checkout another branch in the current directory::
$ git branch
* master
3.5
$ git checkout 3.5
Switched to branch '3.5'
Your branch is up-to-date with 'origin/3.5'.
To verify that your branch has been checked out, enter git branch. After changing branches, it's good practice to run make before executing the tests:
$ git branch
master
* 3.5
$ make
$ make
|
Overall LGTM, just two questions. |
| @@ -267,6 +268,11 @@ Create several clones of your local repository:: | |||
| Switched to branch '3.5' | |||
| Your branch is up-to-date with 'origin/3.5'. | |||
|
|
|||
| Alternatively, if you have a new enough version of git an don't mind using | |||
There was a problem hiding this comment.
probably a typo: an -> and
| ``git fetch``. You can find out if your local copy is up to date with | ||
| its origin by running:: | ||
|
|
||
| $ git remote show origin |
There was a problem hiding this comment.
I think using origin is a bit misleading here. origin will likely be the user's fork so unless they explicitly update their fork this command won't show the actual results. Perhaps we need to add a new FAQ entry about adding a new upstream remote and then use it here?
There was a problem hiding this comment.
If you do so, please add an information how to sync one's fork with current master as well and how to rebase patches, imho. Both of these are valuable information.
There was a problem hiding this comment.
Yes, I agree, this should be fixed and rebase should be mentioned. This is turning into a tutorial about using git for cpython development, though. Does it belong in the FAQ or is there somewhere better (and then this faq entry can link to it).
What I do is clone from the original repo, making that origin, and then add my github clone as the remote 'dev'.
There was a problem hiding this comment.
+1 for the faq entry that can be then linked everywhere where appropriate.
There was a problem hiding this comment.
Maybe we consider not keeping the FAQ around anymore and simply do a good tutorial for using git with cpython development? There's tons of docs online on how to use git unlike Mercurial back in the day, so maybe this whole file will lose its usefulness once we switch to GitHub?
There was a problem hiding this comment.
That's my thought at this point: that a tutorial covering the actions one will want to do with regards to the CPython repo will be the most useful, specifically covering our workflow, including the interaction with the bug tracker. We'll need to fine tune it as we work the latter out.
There was a problem hiding this comment.
OK, then let's just delete the FAQ. I created #27 to track the deletion of the FAW and #28 to track creating a tutorial.
Feel free to close this PR, @bitdancer , or if you want to take on the deletion and repurpose this PR then that's obviously fine as well.
|
LGTM, sorry for writing it confusingly in the first place! |
|
kragniz: your adaptation of what already existed made sense, but I know from personal experience that the instructions to 'compare to the remote branch' is confusing terminology, at least to someone coming from the old CVS/svn world, since I got very confused by it when first starting out with git. |
|
@kragniz, I think you did a good job with this PR. Writing about git is never an easy task since people follow different personal workflows. We appreciate the work that you are doing to make the devguide helpful for all. 🍰 |
|
I'm going to close it. If I do find time to tackle the others, I'll open a new PR. I'm not sure I'm clear on how the workflow will actually work, though, and I'm guessing we won't really be sure until we've done it a few times. |
|
@bitdancer should the branch for this PR be deleted, or did you want to hold on to it? |
You are only ever talking to your local copy of the remote, except for
the new command I added an example of, so I tried to make that clear.
Also fixed a nit with switching branches: you must run make afterward
(at least you do if you expect to test anything). And added a reference to
git worktree...I'm fine if that gets rejected; I haven't used it yet
myself :)