Re: [ANN] Pro Git Reedited 2nd Edition

From: Jon Forrest <nobozo@gmail.com>
Date: Jul 24, 2016, 18:41 UTC
Message-ID: <89e0a631-6396-e56e-0c1d-37acdbf8eda4@gmail.com>
In-Reply-To: <5795087C.4010503@gmail.com>

On 7/24/2016 11:27 AM, Jakub Narębski wrote:

> In my opinion being able to view it online has its advantages.
> Even casual reader can check it, and point errors or offer suggestions
> for improvements.

Absolutely. Now that I've finished the editing I'll look into that.

> I think you can share a folder instead, and this would be stable.
> Alternatively, when updating the book you could update the link
> in the GitHub repository description and/or the README for the
> fork.

I'll check your folder idea. If that's correct then that would be an excellent way to do it. I had already thought of updating the README but I'm not sure if this would be sufficient.

> Well, https://git.github.io/htmldocs/git.html is on GitHub Pages
> (for a project, that is in https://github.com/git/git.github.io repo
> that is also used for Git Rev News), and it obviously uses AsciiDoc.

I'll check that.

Show 6 quoted lines

> You can use Jekyll, or you can just upload HTML, as described
> in https://help.github.com/articles/creating-project-pages-manually/
> (this one is for per-repo GitHub Pages, i.e. using orphan branch
> gh-pages, not a special named repository like e.g. git.github.io).
> After each change / release you would need to rebuild HTML version
> and upload to GitHub pages. This can be automated with hooks.

I'll also look into that.

These are all great suggestions, which I appreciate. I didn't do any of this for the 1st edition, which, in retrospect, was probably a mistake.

> BTW. I thought that Pro Git used Markdown, not AsciiDoc?

Nope. Asciidoc. See https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272#.fdhsp0zgj

> All right. One issue I have after browsing through changes is that
> description of changes and their granularity is severely lacking.
> "A few more very minor changes.", "More piddly changes.", "should have
> included this in last commit" are not good commit messages.

You're absolutely right. I probably should have squashed those commits. Those comments aren't really intended for public consumption. Since I made many changes per commit, I really couldn't give an instructive commit message.

Now that this edition is done, I plan on following good commit practices in the future.

> If I find time to comment on changes, I would do that on GitHub,
> commenting / adding notes on changes there (like the one I posted
> as demo:
>   https://github.com/nobozo/progit2/commit/43ae203c2ccf1a017153de1b41a8c47eb166dba1#commitcomment-18372006

That would be great. I think I'm setup for that now in my GitHub repo for that book.

Jon