|
1 | 1 | <?xml version='1.0' encoding='utf-8'?> |
2 | 2 | <chapter xml:id="ch-collaboration"> |
3 | 3 | <title>Collaborating with Others</title> |
4 | | - <section xml:id="sec-liveshare"> |
5 | | - <title>Live Share</title> |
6 | | - <p> |
7 | | -A nice feature of collaborative authoring tools such |
8 | | -as Google Docs and Overleaf is the ability for several |
9 | | -collaborators to edit the same file synchronously, with |
10 | | -a feature set similar to <c>GitHub.dev</c>. |
11 | | - </p> |
12 | | - <p> |
13 | | -Using the Extensions sidebar, search for and install |
14 | | -Microsoft's <q>Live Share</q> extension. Once installed, |
15 | | -you will have a <q>Live Share</q> option in your |
16 | | -bottom toolar. Clicking it will automatically copy a URL |
17 | | -ending in |
18 | | -<c>https://.../join?[randomStringOfCharacters]</c>. |
19 | | -If you share this URL with a colleague (or |
20 | | -colleagues) you trust, they will be able to collaboratively |
21 | | -edit your repository's text files with you via their web |
22 | | -browser. When you commit your |
23 | | -changes, they will be listed as co-authors of the commit. |
24 | | - </p> |
25 | | - <remark> |
26 | | - <p> |
27 | | -As of writing, my experience with LiveShare has been hit-or-miss, |
28 | | -so I'll suggest another mechanism for live collaboration. |
29 | | -Sometimes when I'm working on a Git repository |
30 | | -with a collague on Zoom, I'll share my screen and give my collaborator |
31 | | -control of my mouse and keyboard, or vice versa. Obviously |
32 | | -you should only do this with a collaborator you trust, but it's |
33 | | -a simple solution to quickly work together on the same repo! |
34 | | - </p> |
35 | | - </remark> |
36 | | - </section> |
37 | 4 | <section xml:id="sec-collaborators-prs"> |
38 | 5 | <title>Collaborators and Pull Requests</title> |
39 | 6 | <p> |
40 | | -A particular downside of Live Share (<xref ref="sec-liveshare"/>) |
41 | | -is that it requires |
42 | | -the repository owner to create the Codespace and provision |
43 | | -the Live Share session. As a result, there's no way for a |
44 | | -collaborator to make a contribution via Live Share to a GitHub project |
45 | | -without the active involvement of the repository owner. |
46 | | - </p> |
47 | | - <p> |
48 | | -To address this, one solution is for the repository owner to |
49 | | -add other GitHub users as collaborators. |
| 7 | +A direct way to allow multiple people you trust to work on the |
| 8 | +same repository is to add these GitHub users as collaborators. |
50 | 9 | </p> |
51 | 10 | <definition xml:id="def-collabotors"> |
52 | 11 | <statement> |
@@ -89,16 +48,19 @@ must name their distinct branches. |
89 | 48 | </warning> |
90 | 49 | <note> |
91 | 50 | <p> |
92 | | -One workflow to support multiple collaborators on the same |
| 51 | +Our recommendation to support multiple collaborators on the same |
93 | 52 | repository is to <em>never directly commit to the <c>main</c> branch</em>, |
94 | 53 | even if you're the owner. |
95 | 54 | </p> |
96 | 55 | <p> |
97 | 56 | To commit to an alternative branch in <c>GitHub.dev</c> or Codespaces, select |
98 | 57 | <c>main</c> in the bottom toolbar, then type the name of your new branch, |
99 | | -and select <q>Create new branch</q>. The name of this branch could |
100 | | -be topical, e.g. <c>add-derivative-chapter</c>, but it's also fine to |
101 | | -pick some other unique identifier, e.g. <c>lastname-YYYY-MM-DD</c>. |
| 58 | +and select <q>Create new branch</q>. It's a good idea to name your |
| 59 | +branch in the form <c>UserName/short-description-of-topic</c>, |
| 60 | +or if you're unsure of the topic, you can just use the current |
| 61 | +date: <c>UserName/YYYYMMDD</c>. Note that prefixing with your |
| 62 | +<c>UserName</c> helps prevent two people from accidentally using the same |
| 63 | +branch name. |
102 | 64 | </p> |
103 | 65 | </note> |
104 | 66 | <p> |
|
0 commit comments