I’ve been asking Bart a lot of questions in the back channel as I struggle to understand the documentation he has provided in our latest few sessions of homework assignments. He had an epiphany last week that he had never explained the documentation methods itself, which was certainly adding to my confusion.
He decided to take a step back and explain step by step using video. He created a video screencast of the entire process of creating documentation using JSDoc. Then during the audio recording you’ll hear in the podcast, he walked through it again while I asked him (lots of) questions. Hopefully it will be as eye opening to you as it was to me. He also demonstrates his favorite tools for the process.
You can find Bart’s blog post with the embedded video screencast at pbs.bartificer.net/…
In defense of the “pull request” nomenclature.
Allison,
While you may find the “pull request” backward, it does describe well what the designers of the git system have in mind. As you spend more time in developer docs and culture you’ll start seeing phrases like “up stream changes” crop up a lot, this leads to the “pull request” nomenclature.
Let’s use Bart’s xkpasswd repository (repo for short) as the example.
Bart conceived the project and created it, this makes him the source of everything xkpasswd. Being a beneficent being, Bart allows us access to the code and application. This creates the “stream” where Bart is the source, or the head, of the stream. Any change Bart makes would flow down to those “below” him in the order/stream of the code.
Along comes, Allison. She has found a bug or has a great idea for a feature in xkpasswd. She forks the code (also creating a fork in the stream) and writes up her change. Now that her version is in her repo, someone could use her version, and maybe not use Bart’s. This is fairly common in OSS.
Allison is also a beneficent sort, and wants *everyone* to benefit from her change. But she can’t _push_ the change up the stream, the current, aka the permissions, won’t allow it. But, she can alert Bart to the fact that there is a change that would benefit the greater project; this is the “pull request”.
Now that Bart knows there is something “down stream” that he might want, he can _pull_ it up into his version. This will put the change into the head of the stream and it will flow down it the next release.
If Allison makes many good changes & pull requests, Bart may opt to give her a “commit bit” which will allow Allison to push a change into the head of the stream. Bart still retains ownership and can revoke or roll back changes but, usually once a commit bit is given the holder understands their responsibility.
Hopefully that helps clarify things, and hopefully I wasn’t too pedantic.