Skip to content

Commit 491dbc5

Browse files
mheapmheap
authored
Add Code Tour (#58)
1 parent 63988d6 commit 491dbc5

File tree

2 files changed

+230
-0
lines changed

2 files changed

+230
-0
lines changed

‎.devcontainer/devcontainer.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"extensions": ["vsls-contrib.codetour"]
3+
}

‎.tours/github-default-branch.tour

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
{
2+
"$schema": "https://aka.ms/codetour-schema",
3+
"title": "github-default-branch",
4+
"steps": [
5+
{
6+
"file": "package.json",
7+
"line": 31,
8+
"description": "github-default-branch's main entrypoint is bin/github-default-branch"
9+
},
10+
{
11+
"file": "bin/github-default-branch",
12+
"line": 3,
13+
"description": "bin/github-default-branch handles all of the argument parsing from the command line"
14+
},
15+
{
16+
"file": "bin/github-default-branch",
17+
"line": 4,
18+
"description": "github-default-branch uses the `debug` module to add log messages. You can see them all by setting the environment variable `DEBUG=\"ghdb*\"`"
19+
},
20+
{
21+
"file": "bin/github-default-branch",
22+
"line": 125,
23+
"description": "Before delegating to `run()`, which is the function exported by our `index.js` file"
24+
},
25+
{
26+
"file": "bin/github-default-branch",
27+
"line": 121,
28+
"description": "Plus a `confirmation` step that ensures that the user wants to proceed"
29+
},
30+
{
31+
"file": "index.js",
32+
"line": 12,
33+
"description": "We use `octokit` to call the GitHub API"
34+
},
35+
{
36+
"file": "src/octokit.js",
37+
"line": 6,
38+
"description": "Including plugins for enterprise compatibility if `--enterprise-compatibility` is passed"
39+
},
40+
{
41+
"file": "src/octokit.js",
42+
"line": 14,
43+
"description": "And a plugin to manage rate limiting. This tool can make a *lot* of API calls if running against an organization, so having logic to wait until our rate limit resets is important"
44+
},
45+
{
46+
"file": "index.js",
47+
"line": 22,
48+
"description": "The first thing to do is fetch a list of repos to update"
49+
},
50+
{
51+
"file": "data-sources/list-repos.js",
52+
"line": 12,
53+
"description": "The user can provide a single repo name (`--repo`)"
54+
},
55+
{
56+
"file": "data-sources/list-repos.js",
57+
"line": 19,
58+
"description": "An organization name (`--org`)"
59+
},
60+
{
61+
"file": "data-sources/list-repos.js",
62+
"line": 30,
63+
"description": "An organization *and* a team name to fetch repos that a team has access to (`--org` and `--team`)"
64+
},
65+
{
66+
"file": "data-sources/list-repos.js",
67+
"line": 42,
68+
"description": "Or a user name (`--user`)"
69+
},
70+
{
71+
"file": "data-sources/list-repos.js",
72+
"line": 59,
73+
"description": "Then we skip forks if `--skip-forks` was provided"
74+
},
75+
{
76+
"file": "data-sources/list-repos.js",
77+
"line": 69,
78+
"description": "Remove any archived repos as we can't edit them"
79+
},
80+
{
81+
"file": "data-sources/list-repos.js",
82+
"line": 76,
83+
"description": "And return a list of repo names"
84+
},
85+
{
86+
"file": "index.js",
87+
"line": 27,
88+
"description": "Then for each repo, we update the branch from `old` to `target`"
89+
},
90+
{
91+
"file": "index.js",
92+
"line": 40,
93+
"description": "We need to know the current `sha` of the existing `old` branch"
94+
},
95+
{
96+
"file": "index.js",
97+
"line": 48,
98+
"description": "Then we apply a list of transforms in order. The first is always to create a new branch with the same `sha` as the existing branch"
99+
},
100+
{
101+
"file": "index.js",
102+
"line": 50,
103+
"description": "Then we update the default branch in the repository settings"
104+
},
105+
{
106+
"file": "index.js",
107+
"line": 51,
108+
"description": "Update the source for any repos using GitHub Pages"
109+
},
110+
{
111+
"file": "index.js",
112+
"line": 52,
113+
"description": "Retarget any open pull requests"
114+
},
115+
{
116+
"file": "index.js",
117+
"line": 53,
118+
"description": "Update any branch protection rules to prevent direct pushes to the new branch"
119+
},
120+
{
121+
"file": "index.js",
122+
"line": 54,
123+
"description": "Then finally, delete the old branch"
124+
},
125+
{
126+
"file": "index.js",
127+
"line": 59,
128+
"description": "Any of these transforms can be skipped by providing a CLI flag matching the name of the transform, with `--skip-` prefixed e.g. `--skip-github-pages`"
129+
},
130+
{
131+
"file": "transforms/github-pages.js",
132+
"line": 1,
133+
"description": "Let's take a look at how a transform works. In this case, it's our GitHub Pages transform. \n\nAll of the information we have available is passed in to the transform, providing the old and target branch name, plus the repository name and owner"
134+
},
135+
{
136+
"file": "transforms/github-pages.js",
137+
"line": 10,
138+
"description": "We create a new debug logger with a `github-pages` prefix to make it easy to see what this transform is doing in the logs"
139+
},
140+
{
141+
"file": "transforms/github-pages.js",
142+
"line": 17,
143+
"description": "Most transforms start by reading the current configuration. In this case we're loading the current GitHub pages settings"
144+
},
145+
{
146+
"file": "transforms/github-pages.js",
147+
"line": 22,
148+
"description": "We need to check that the current configuration is pointing to our old branch. If it is not, we should not update the configuration."
149+
},
150+
{
151+
"file": "transforms/github-pages.js",
152+
"line": 29,
153+
"description": "Next, we update the config to point at our new `target` branch"
154+
},
155+
{
156+
"file": "transforms/github-pages.js",
157+
"line": 31,
158+
"description": "Before calling the API again to update the settings. At this point our transform is complete"
159+
},
160+
{
161+
"file": "transforms/github-pages.js",
162+
"line": 41,
163+
"description": "It's worth mentioning that some transforms may not be applicable to all repos. In this case, Octokit will throw an error if it cannot fetch the GitHub Pages configuration (if the repo does not use GitHub Pages). In this case we log the error and continue, as it's an expected failure case"
164+
},
165+
{
166+
"file": "index.js",
167+
"line": 70,
168+
"description": "Back to `index.js`, the final thing to do is update any file contents using `src/update-content`"
169+
},
170+
{
171+
"file": "src/update-content.js",
172+
"line": 9,
173+
"description": "Replacements live in the `replacements` folder at the root of the repository"
174+
},
175+
{
176+
"file": "src/update-content.js",
177+
"line": 15,
178+
"description": "We read all replacement files and build an object containing all transforms to apply, using the file path as a key. This allows us to touch each file a single time and apply all changes at once"
179+
},
180+
{
181+
"file": "src/update-content.js",
182+
"line": 26,
183+
"description": "For each path detected, we load the file contents using the API"
184+
},
185+
{
186+
"file": "src/update-content.js",
187+
"line": 30,
188+
"description": "Replace all of the occurences of the `from` string with the `to` string"
189+
},
190+
{
191+
"file": "src/update-content.js",
192+
"line": 40,
193+
"description": "Then write the file to the repo if it has changed"
194+
},
195+
{
196+
"file": "replacements/readme.js",
197+
"line": 3,
198+
"description": "Here is an example replacements file that targets the `README.md` file"
199+
},
200+
{
201+
"file": "replacements/readme.js",
202+
"line": 6,
203+
"description": "We replace `@old` with `@target`"
204+
},
205+
{
206+
"file": "replacements/readme.js",
207+
"line": 10,
208+
"description": "Along with any badges (such as Travis CI build badges) in the text"
209+
},
210+
{
211+
"file": "index.js",
212+
"line": 27,
213+
"description": "Then we do it all again for the next repo!"
214+
},
215+
{
216+
"file": "index.js",
217+
"line": 75,
218+
"description": "Once all repos have been updated, our function exits"
219+
},
220+
{
221+
"file": "bin/github-default-branch",
222+
"line": 127,
223+
"description": "And we tell the user that our job is complete"
224+
}
225+
],
226+
"isPrimary": true
227+
}

0 commit comments

Comments
 (0)