RFC - Git Developer Blog

RFC - Git Developer Blog

[Emily Shaffer]

Hi all,

In backchannels recently there has been some discussion about the idea
of a Git-project-blessed blog written by Git contributors, generally
covering usability tips or overviews of the internals of Git which the
general public tend to find confusing.

Ideally, we could use a channel like this to make Git better understood
in the rest of the world, in a less formal setting than the man pages or
gittutorial. I think it would be valuable to have resources which have
been reviewed and endorsed by the Git contributor community, in addition
to individual company blogs. (It might even make sense for contributors
who would normally post this kind of thing to their company blog to
cross-post the content in both places.)

Are folks interested in writing and reviewing this kind of content? Any
ideas for where we may be able to host (maybe git-scm)? It could make
sense to review contributions like this on the mailing list, so that we
get the attention of those who wrote the features that are being covered
in the blog posts - are we okay with the additional traffic?

Some example topics, from the top of my head:

 - Using `git worktree` Effectively
 - Overview of the Git Object Store
 - Finding Regressions with `git bisect`
 - Life of a Git Remote Request

The idea is that we could cover high level topics stringing together
multiple components or giving power user advice, which we can't really
do with the manpages.

Thoughts?

 - Emily

Re: RFC - Git Developer Blog

[Junio C Hamano]

Emily Shaffer <emilyshaffer@google.com> writes:

> In backchannels recently there has been some discussion about the idea
> of a Git-project-blessed blog written by Git contributors, generally
> covering usability tips or overviews of the internals of Git which the
> general public tend to find confusing.
> ...
> The idea is that we could cover high level topics stringing together
> multiple components or giving power user advice, which we can't really
> do with the manpages.
>
> Thoughts?

Interesting.

I recall that I used to do the "Fun with ..." series back when I was
more into use-case-exploration mode; writing those articles was fun,
but it took a lot of time and quite an effort, so I stopped after
writing enough.  

Making it a group effort may help by allowing writers and reviewers
to encourage each other.

Re: RFC - Git Developer Blog

[Christian Couder]

On Tue, Aug 6, 2019 at 5:35 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Emily Shaffer <emilyshaffer@google.com> writes:
>
> > In backchannels recently there has been some discussion about the idea
> > of a Git-project-blessed blog written by Git contributors, generally
> > covering usability tips or overviews of the internals of Git which the
> > general public tend to find confusing.
> > ...
> > The idea is that we could cover high level topics stringing together
> > multiple components or giving power user advice, which we can't really
> > do with the manpages.
> >
> > Thoughts?
>
> Interesting.
>
> I recall that I used to do the "Fun with ..." series back when I was
> more into use-case-exploration mode; writing those articles was fun,
> but it took a lot of time and quite an effort, so I stopped after
> writing enough.

Linux-Kongress (LK) was a conference organized by the German Unix User
Group from 1994 to 2010. They asked authors of accepted submissions
for the technical sessions to provide a paper for publication in the
conference proceedings. As I wanted to give a presentation at LK 2009,
I wrote a paper about git bisect and asked kind souls (like Junio) to
review it on the mailing list. A bit later it was included in the Git
documentation and is still there:

https://git-scm.com/docs/git-bisect-lk2009.html

The git bisect man page links to it, but I must say that it tends to
be a bit obsolete as it has not really been updated.

There are also "guides" that are part of the actual documentation and
can be listed using `git help -g`.

> Making it a group effort may help by allowing writers and reviewers
> to encourage each other.

When Git Rev News was started I thought that there could be such a
group effort to encourage each other to publish articles in it, but I
must say that outside the group of editors (currently Jakub, Markus,
Gabriel and me) it hasn't happened much.

Each month though there are a small number of people helping on
smaller things like short news, typos, releases, etc. And people who
are interviewed are doing a great job when they accept to be
interviewed.

Maybe it's also not clear that we could accept other kind of articles
than just articles focused on what happens on the mailing list. I
think we have generally tried to highlight articles by Git developers
that were published on their blogs or their company's blog though.

In any case if you or others would like to join the editor group to
focus on other kind of articles, or just to help a bit, you are most
welcome!

I would also be ok to change the form of Git Rev News if there is an
official blog. For example the "Discussions" section could become
something like "Featured articles" with links to articles on the blog.

Re: RFC - Git Developer Blog

[Jeff King]

On Tue, Aug 06, 2019 at 06:59:21AM +0200, Christian Couder wrote:

> When Git Rev News was started I thought that there could be such a
> group effort to encourage each other to publish articles in it, but I
> must say that outside the group of editors (currently Jakub, Markus,
> Gabriel and me) it hasn't happened much.
> 
> Each month though there are a small number of people helping on
> smaller things like short news, typos, releases, etc. And people who
> are interviewed are doing a great job when they accept to be
> interviewed.
> 
> Maybe it's also not clear that we could accept other kind of articles
> than just articles focused on what happens on the mailing list. I
> think we have generally tried to highlight articles by Git developers
> that were published on their blogs or their company's blog though.

I think the audience may be a bit different for Rev News versus a blog.
I'd expect the blog to be written for people who use Git, and want to
learn how to use new features, or maybe broaden their understanding of
it. Rev News seems a lot more technical to me, and mostly of interest to
people who are part of the development community.

Which isn't to say those two things can't co-exist on a site[1] or a
blog. But I think there needs to be some way for people to subscribe to
one but not the other. Because I suspect that too many posts about the
development process would drive away users who would be interested in
the less-technical posts.

-Peff

[1] By the way, Rev News lives over at git.github.io, but there's no
    reason it couldn't be integrated (from the user's perspective) with
    the git-scm.org site.

    I wouldn't want it in the same repo for technical reasons, but it
    could be revnews.git-scm.com or similar (and possibly styled in a
    similar way).

    If you're happy with it separate, I have no objections. I just
    wanted to make it clear it's an option.

Re: RFC - Git Developer Blog

[Emily Shaffer]

On Tue, Aug 06, 2019 at 09:27:30AM -0400, Jeff King wrote:
> On Tue, Aug 06, 2019 at 06:59:21AM +0200, Christian Couder wrote:
> 
> > When Git Rev News was started I thought that there could be such a
> > group effort to encourage each other to publish articles in it, but I
> > must say that outside the group of editors (currently Jakub, Markus,
> > Gabriel and me) it hasn't happened much.
> > 
> > Each month though there are a small number of people helping on
> > smaller things like short news, typos, releases, etc. And people who
> > are interviewed are doing a great job when they accept to be
> > interviewed.
> > 
> > Maybe it's also not clear that we could accept other kind of articles
> > than just articles focused on what happens on the mailing list. I
> > think we have generally tried to highlight articles by Git developers
> > that were published on their blogs or their company's blog though.

Wow, I definitely didn't realize that was an option - I have a couple of
Git-centric personal blog posts I probably would have sent along. Oops.

> 
> I think the audience may be a bit different for Rev News versus a blog.
> I'd expect the blog to be written for people who use Git, and want to
> learn how to use new features, or maybe broaden their understanding of
> it. Rev News seems a lot more technical to me, and mostly of interest to
> people who are part of the development community.

I wonder, though, whether it helps enforce the ephemeral nature of blog
posts like this: "Here is an interesting topic, which is valid as of
2.whatever, and we probably aren't going to come back and update this at
3.0 release."  (At least, that's the kind of maintenance I'd prefer to
do for this kind of blog. :) )

> 
> Which isn't to say those two things can't co-exist on a site[1] or a
> blog. But I think there needs to be some way for people to subscribe to
> one but not the other. Because I suspect that too many posts about the
> development process would drive away users who would be interested in
> the less-technical posts.

That's a good point, and one I wouldn't have considered since I don't
use RSS to subscribe to things anymore :) It seems reasonable, to me, to
roll up all this stuff under git-scm domain - because it wasn't clear to
me that git-scm existed primarily to host Pro Git. I thought it was "the
official Git website" until only very recently. Perhaps I didn't read
well enough. :)

There does seem like a reasonable case to have a separation between Pro
Git, Rev News, and this blog thing.

> 
> -Peff
> 
> [1] By the way, Rev News lives over at git.github.io, but there's no
>     reason it couldn't be integrated (from the user's perspective) with
>     the git-scm.org site.
> 
>     I wouldn't want it in the same repo for technical reasons, but it
>     could be revnews.git-scm.com or similar (and possibly styled in a
>     similar way).
> 
>     If you're happy with it separate, I have no objections. I just
>     wanted to make it clear it's an option.

Re: RFC - Git Developer Blog

[Taylor Blau]

On Tue, Aug 06, 2019 at 09:27:30AM -0400, Jeff King wrote:
> On Tue, Aug 06, 2019 at 06:59:21AM +0200, Christian Couder wrote:
>
> > When Git Rev News was started I thought that there could be such a
> > group effort to encourage each other to publish articles in it, but I
> > must say that outside the group of editors (currently Jakub, Markus,
> > Gabriel and me) it hasn't happened much.
> >
> > Each month though there are a small number of people helping on
> > smaller things like short news, typos, releases, etc. And people who
> > are interviewed are doing a great job when they accept to be
> > interviewed.
> >
> > Maybe it's also not clear that we could accept other kind of articles
> > than just articles focused on what happens on the mailing list. I
> > think we have generally tried to highlight articles by Git developers
> > that were published on their blogs or their company's blog though.
>
> I think the audience may be a bit different for Rev News versus a blog.
> I'd expect the blog to be written for people who use Git, and want to
> learn how to use new features, or maybe broaden their understanding of
> it. Rev News seems a lot more technical to me, and mostly of interest to
> people who are part of the development community.

Yeah, I agree and share the view that the audience between the two is
definitely different, at least if I'm understanding the purpose of this
new proposal correctly.

I quite enjoy reading Rev News, because it does a great job at
summarizing all of the on-list development. So, if I haven't had enough
time to stay up-to-date on it myself, I know that Rev News has.

But, I'm not sure that it holds the same interest for folks who don't
participate in development. Perhaps there are some willing spectators
who might be curious about what's going on, but I get the general sense
that the majority of Git users would be primarily interested in news
other than what's currently on Rev News.

> Which isn't to say those two things can't co-exist on a site[1] or a
> blog. But I think there needs to be some way for people to subscribe to
> one but not the other. Because I suspect that too many posts about the
> development process would drive away users who would be interested in
> the less-technical posts.

This is an interesting idea. I don't really have a strong preference
either way whether a new blog be grafted onto the existing Rev News
site, but I do think that the two should be separate.

> -Peff
>
> [1] By the way, Rev News lives over at git.github.io, but there's no
>     reason it couldn't be integrated (from the user's perspective) with
>     the git-scm.org site.
>
>     I wouldn't want it in the same repo for technical reasons, but it
>     could be revnews.git-scm.com or similar (and possibly styled in a
>     similar way).
>
>     If you're happy with it separate, I have no objections. I just
>     wanted to make it clear it's an option.

Thanks,
Taylor

Re: RFC - Git Developer Blog

[Andrew Ardill]

On Tue, 6 Aug 2019 at 11:51, Emily Shaffer <emilyshaffer@google.com> wrote:

> Are folks interested in writing and reviewing this kind of content?

The idea sounds great, and I would be happy to review content - even
if it's only for readability and spelling!

In terms of collaborating, I've found the processes over at Git Rev
News[0] straightforward and sensible, if you're looking for ideas.

Regards,

Andrew Ardill

[0] https://git.github.io/rev_news/rev_news/

Re: RFC - Git Developer Blog

[Derrick Stolee]

On 8/6/2019 12:52 AM, Andrew Ardill wrote:
> On Tue, 6 Aug 2019 at 11:51, Emily Shaffer <emilyshaffer@google.com> wrote:
> 
>> Are folks interested in writing and reviewing this kind of content?

I am interested in writing and reviewing! Here are some topics I am
interested in writing:

* Updates to the commit-graph feature
* What is a multi-pack-index and what is it for?
* Git at Scale: What makes a repo big, and how to avoid it?
* Advanced Git config settings

Here are some topics I'd be interested in seeing in the wild
(and was considering writing them myself if I didn't see them elsewhere):

* Partial clone: what, why, and how?
* Life cycle of a patch series
* Crafting perfect patches with interactive add and rebase

It would also be helpful to have a post for every major release
highlighting new features and giving users examples of how to use them.
Taylor has been writing these on the GitHub blog [1], but maybe he
would be interested in writing them for this new venue?

[1] https://github.blog/2019-06-07-highlights-from-git-2-22/

> The idea sounds great, and I would be happy to review content - even
> if it's only for readability and spelling!
> 
> In terms of collaborating, I've found the processes over at Git Rev
> News[0] straightforward and sensible, if you're looking for ideas.

I agree that the review process there is helpful, and users contributing
edits via PRs to a feature branch works quite well. I would also suggest
writing a "request for review" on the mailing list before merging any
pull requests.

One goal I think would be important is that this blog is that the posts
come with some amount of blessing from "the Git Dev Community". That is,
they should be service-agnostic and focused on helping _all_ Git users.

That said, I also suggest that the authors can list their professional
affiliation as some minimum amount of credit to their employers. Something
as simple as "Author: Derrick Stolee, Microsoft" would go a long way to
justifying the work it takes to write these on the community blog and not
a company-owned blog.
 
Thanks,
-Stolee

Re: RFC - Git Developer Blog

[Emily Shaffer]

On Tue, Aug 06, 2019 at 08:19:15AM -0400, Derrick Stolee wrote:
> On 8/6/2019 12:52 AM, Andrew Ardill wrote:
> > On Tue, 6 Aug 2019 at 11:51, Emily Shaffer <emilyshaffer@google.com> wrote:
> > 
> >> Are folks interested in writing and reviewing this kind of content?
> 
> I am interested in writing and reviewing! Here are some topics I am
> interested in writing:
> 
> * Updates to the commit-graph feature
> * What is a multi-pack-index and what is it for?
> * Git at Scale: What makes a repo big, and how to avoid it?
> * Advanced Git config settings
> 
> Here are some topics I'd be interested in seeing in the wild
> (and was considering writing them myself if I didn't see them elsewhere):
> 
> * Partial clone: what, why, and how?
> * Life cycle of a patch series
> * Crafting perfect patches with interactive add and rebase
Oh, I'd love to write one on interactive add and rebase. Maybe it's
weird to have a favorite Git feature, but mine's add -p :)

Since we're volunteering, my todo list for my personal blog also
contains:

 - How to use bisect
 - How to use Git pathspecs

I also have a couple pre-existing personal blog posts on
nasamuffin.github.io:

 - How to use git format-patch and git send-email for mailing list based
   reviews
 - Overview of Git object types

> 
> It would also be helpful to have a post for every major release
> highlighting new features and giving users examples of how to use them.
> Taylor has been writing these on the GitHub blog [1], but maybe he
> would be interested in writing them for this new venue?
> 
> [1] https://github.blog/2019-06-07-highlights-from-git-2-22/
> 
> > The idea sounds great, and I would be happy to review content - even
> > if it's only for readability and spelling!
> > 
> > In terms of collaborating, I've found the processes over at Git Rev
> > News[0] straightforward and sensible, if you're looking for ideas.
> 
> I agree that the review process there is helpful, and users contributing
> edits via PRs to a feature branch works quite well. I would also suggest
> writing a "request for review" on the mailing list before merging any
> pull requests.
> 
> One goal I think would be important is that this blog is that the posts
> come with some amount of blessing from "the Git Dev Community". That is,
> they should be service-agnostic and focused on helping _all_ Git users.

By this do you mean "not about how to use Git with Github", or "not
about how to use Git for Windows"? I initially read it as the latter but
I think you mean the former, right?

I believe there's a lot of value in the former - lately it seems to me
like the lines are really blurred between which parts are Git and which
parts are Github. It'd be nice to clear up some of that confusion and
writing pieces concerning "vanilla Git".

> That said, I also suggest that the authors can list their professional
> affiliation as some minimum amount of credit to their employers. Something
> as simple as "Author: Derrick Stolee, Microsoft" would go a long way to
> justifying the work it takes to write these on the community blog and not
> a company-owned blog.

Yes, I agree - this seems to have a double win of lending credibility to
the author and giving good optics for the company. Plus, as mentioned
before, crossposting seems like a good fit here.

>  
> Thanks,
> -Stolee

Re: RFC - Git Developer Blog

[Taylor Blau]

Hi Emily,

On Tue, Aug 06, 2019 at 02:00:15PM -0700, Emily Shaffer wrote:
> On Tue, Aug 06, 2019 at 08:19:15AM -0400, Derrick Stolee wrote:
> > On 8/6/2019 12:52 AM, Andrew Ardill wrote:
> > > On Tue, 6 Aug 2019 at 11:51, Emily Shaffer <emilyshaffer@google.com> wrote:
> > >
> > >> Are folks interested in writing and reviewing this kind of content?
> >
> > I am interested in writing and reviewing! Here are some topics I am
> > interested in writing:
> >
> > * Updates to the commit-graph feature
> > * What is a multi-pack-index and what is it for?
> > * Git at Scale: What makes a repo big, and how to avoid it?
> > * Advanced Git config settings
> >
> > Here are some topics I'd be interested in seeing in the wild
> > (and was considering writing them myself if I didn't see them elsewhere):
> >
> > * Partial clone: what, why, and how?
> > * Life cycle of a patch series
> > * Crafting perfect patches with interactive add and rebase
> Oh, I'd love to write one on interactive add and rebase. Maybe it's
> weird to have a favorite Git feature, but mine's add -p :)
>
> Since we're volunteering, my todo list for my personal blog also
> contains:
>
>  - How to use bisect
>  - How to use Git pathspecs
>
> I also have a couple pre-existing personal blog posts on
> nasamuffin.github.io:
>
>  - How to use git format-patch and git send-email for mailing list based
>    reviews
>  - Overview of Git object types
>
> >
> > It would also be helpful to have a post for every major release
> > highlighting new features and giving users examples of how to use them.
> > Taylor has been writing these on the GitHub blog [1], but maybe he
> > would be interested in writing them for this new venue?
> >
> > [1] https://github.blog/2019-06-07-highlights-from-git-2-22/
> >
> > > The idea sounds great, and I would be happy to review content - even
> > > if it's only for readability and spelling!
> > >
> > > In terms of collaborating, I've found the processes over at Git Rev
> > > News[0] straightforward and sensible, if you're looking for ideas.
> >
> > I agree that the review process there is helpful, and users contributing
> > edits via PRs to a feature branch works quite well. I would also suggest
> > writing a "request for review" on the mailing list before merging any
> > pull requests.
> >
> > One goal I think would be important is that this blog is that the posts
> > come with some amount of blessing from "the Git Dev Community". That is,
> > they should be service-agnostic and focused on helping _all_ Git users.
>
> By this do you mean "not about how to use Git with Github", or "not
> about how to use Git for Windows"? I initially read it as the latter but
> I think you mean the former, right?
>
> I believe there's a lot of value in the former - lately it seems to me
> like the lines are really blurred between which parts are Git and which
> parts are Github. It'd be nice to clear up some of that confusion and
> writing pieces concerning "vanilla Git".

Yeah, this is a concern of mine, too. I try and make quite clear that
GitHub isn't the author of these features (we are for some, but
obviously not all), and instead that we're merely summarizing the
interesting work that's happening upstream, and that the project is, of
course, open-source.

The posts aren't really a "using Git with GitHub" guide, per-se,
although we usually will have remotes with 'git@github.com' in them when
included in examples.

> > That said, I also suggest that the authors can list their professional
> > affiliation as some minimum amount of credit to their employers. Something
> > as simple as "Author: Derrick Stolee, Microsoft" would go a long way to
> > justifying the work it takes to write these on the community blog and not
> > a company-owned blog.
>
> Yes, I agree - this seems to have a double win of lending credibility to
> the author and giving good optics for the company. Plus, as mentioned
> before, crossposting seems like a good fit here.

Doubly agreed. I am considering proposing a blog post about some of the
work around alternates that we have done upstream, and the impact it's
had on GitHub. This sort of walks the line between talking about an
upstream contribution and a more traditional corporate engineering blog
post, so I think that type of content certainly belongs on a comapny
blog.

> > Thanks,
> > -Stolee

Thanks,
Taylor

Re: RFC - Git Developer Blog

[Taylor Blau]

Hi Stolee,

On Tue, Aug 06, 2019 at 08:19:15AM -0400, Derrick Stolee wrote:
> On 8/6/2019 12:52 AM, Andrew Ardill wrote:
> > On Tue, 6 Aug 2019 at 11:51, Emily Shaffer <emilyshaffer@google.com> wrote:
> >
> >> Are folks interested in writing and reviewing this kind of content?
>
> I am interested in writing and reviewing! Here are some topics I am
> interested in writing:
>
> * Updates to the commit-graph feature
> * What is a multi-pack-index and what is it for?
> * Git at Scale: What makes a repo big, and how to avoid it?
> * Advanced Git config settings
>
> Here are some topics I'd be interested in seeing in the wild
> (and was considering writing them myself if I didn't see them elsewhere):
>
> * Partial clone: what, why, and how?
> * Life cycle of a patch series
> * Crafting perfect patches with interactive add and rebase
>
> It would also be helpful to have a post for every major release
> highlighting new features and giving users examples of how to use them.
> Taylor has been writing these on the GitHub blog [1], but maybe he
> would be interested in writing them for this new venue?
>
> [1] https://github.blog/2019-06-07-highlights-from-git-2-22/

Yes, I generally try and publish a blog post once-per-release, and
generally with the following two goals in mind:

  - talk about and publicize some of the new features in the latest
    release (or releases, if I've missed a blog post or two)

  - share some interesting tidbits about existing features.

I think it would be good to have these blog posts in both places, should
this proposal materialize. I would have to ask about whether or not
GitHub would be comfortable about cross-posting to a new venue, and I'd
be happy to raise the question when it comes up.

> [...]
>
> Thanks,
> -Stolee

Thanks,
Taylor

Re: RFC - Git Developer Blog

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> writes:

>> It would also be helpful to have a post for every major release
>> highlighting new features and giving users examples of how to use them.
>> Taylor has been writing these on the GitHub blog [1], but maybe he
>> would be interested in writing them for this new venue?
>>
>> [1] https://github.blog/2019-06-07-highlights-from-git-2-22/
>
> Yes, I generally try and publish a blog post once-per-release, and
> generally with the following two goals in mind:
>
>   - talk about and publicize some of the new features in the latest
>     release (or releases, if I've missed a blog post or two)
>
>   - share some interesting tidbits about existing features.
>
> I think it would be good to have these blog posts in both places, should
> this proposal materialize. I would have to ask about whether or not
> GitHub would be comfortable about cross-posting to a new venue, and I'd
> be happy to raise the question when it comes up.

Yeah, I find these blog postings at GitHub quite helpful.  Thanks
for writing them.

I wonder if a semi-automated republication (ala "Planet"), instead
of cross-posting, is an option that is easier to manage, though.

Re: RFC - Git Developer Blog

[Taylor Blau]

On Wed, Aug 07, 2019 at 10:15:43AM -0700, Junio C Hamano wrote:
> Taylor Blau <me@ttaylorr.com> writes:
>
> >> It would also be helpful to have a post for every major release
> >> highlighting new features and giving users examples of how to use them.
> >> Taylor has been writing these on the GitHub blog [1], but maybe he
> >> would be interested in writing them for this new venue?
> >>
> >> [1] https://github.blog/2019-06-07-highlights-from-git-2-22/
> >
> > Yes, I generally try and publish a blog post once-per-release, and
> > generally with the following two goals in mind:
> >
> >   - talk about and publicize some of the new features in the latest
> >     release (or releases, if I've missed a blog post or two)
> >
> >   - share some interesting tidbits about existing features.
> >
> > I think it would be good to have these blog posts in both places, should
> > this proposal materialize. I would have to ask about whether or not
> > GitHub would be comfortable about cross-posting to a new venue, and I'd
> > be happy to raise the question when it comes up.
>
> Yeah, I find these blog postings at GitHub quite helpful.  Thanks
> for writing them.

Thanks for maintaining the release notes. I often start there to figure
out what to write about, and having them so well organized makes my job
a lot easier.

> I wonder if a semi-automated republication (ala "Planet"), instead
> of cross-posting, is an option that is easier to manage, though.

Probably. I don't know how Planet works, but if it can accept an RSS
feed (and doesn't require too much on GitHub's end), it's probably
sensible.


Thanks,
Taylor

Re: RFC - Git Developer Blog

[Jeff King]

On Mon, Aug 05, 2019 at 06:49:35PM -0700, Emily Shaffer wrote:

> Are folks interested in writing and reviewing this kind of content? Any
> ideas for where we may be able to host (maybe git-scm)?

I think it would make sense to have blog.git-scm.com (and .org) with
this content. I'd be happy to deal with the technical side of setting
the name up. I think it should live in a different repository than the
main site, though (which is an overly-messy Rails app).

There actually used to be a blog section on the site. It discussed
various high-level concepts that hadn't made it into the Pro Git book
(whose content makes up most of the site). But as most of those were
eventually added to the book, the blog posts became staler versions of
the same content, and we dropped them.

Just to play devil's advocate for a moment: another venue for topics
like these:

>  - Using `git worktree` Effectively
>  - Overview of the Git Object Store
>  - Finding Regressions with `git bisect`
>  - Life of a Git Remote Request

might be to actually add them to the book (which started as a
single-author publication, but is CC-licensed and has taken lots of
community content over the years). The advantage there is that the book
content would always represent the most up-to-date coverage of those
topics, whereas blog posts sometimes grow stale over the years as nobody
is interested in updating them.

One downside is that it may be more annoying to try to integrate content
into the existing structure of the book. Another is that a blog is
something people subscribe to, so a post may generate attention/interest
in a topic (but nobody wants to see a feed of book updates!). A prime
example is something like a highlight of features after a new release,
which is not book content at all, and just serves to generate attention.
:)

So I don't think I'm really seriously suggesting this as an alternative,
but maybe something to ponder.

> It could make sense to review contributions like this on the mailing
> list, so that we get the attention of those who wrote the features
> that are being covered in the blog posts - are we okay with the
> additional traffic?

Additional traffic is fine. I do suspect that blog posts in particular
would benefit from a more integrated review system like GitHub (or
similar):

  - I'd expect there to be a lot of images, and those systems make
    image diffs easy to see

  - the formatted output is going to be important to review; a
    browser-based review system makes it easier to see the formatted
    output (especially if they're written in markdown)

  - we're more likely to get/want drive-by fixes like typo corrections,
    so reducing friction for non-regular contributors is more important

Obviously you can apply many of the same mailing list vs web review
arguments that we've already had for writing Git itself (e.g., is
reviewing formatted output much different than looking at the output of
a compiled program?). But I think the nature of blog posts pushes it a
bit further towards web-based review.

-Peff

Re: RFC - Git Developer Blog

[Emily Shaffer]

On Tue, Aug 06, 2019 at 09:20:52AM -0400, Jeff King wrote:
> On Mon, Aug 05, 2019 at 06:49:35PM -0700, Emily Shaffer wrote:
> 
> > Are folks interested in writing and reviewing this kind of content? Any
> > ideas for where we may be able to host (maybe git-scm)?
> 
> I think it would make sense to have blog.git-scm.com (and .org) with
> this content. I'd be happy to deal with the technical side of setting
> the name up. I think it should live in a different repository than the
> main site, though (which is an overly-messy Rails app).

I'd certainly be happy with that setup if others agree, although the
incorporation with Git Rev News sounds interesting too (I'll reply to
that post also).

> 
> There actually used to be a blog section on the site. It discussed
> various high-level concepts that hadn't made it into the Pro Git book
> (whose content makes up most of the site). But as most of those were
> eventually added to the book, the blog posts became staler versions of
> the same content, and we dropped them.
> 
> Just to play devil's advocate for a moment: another venue for topics
> like these:
> 
> >  - Using `git worktree` Effectively
> >  - Overview of the Git Object Store
> >  - Finding Regressions with `git bisect`
> >  - Life of a Git Remote Request
> 
> might be to actually add them to the book (which started as a
> single-author publication, but is CC-licensed and has taken lots of
> community content over the years). The advantage there is that the book
> content would always represent the most up-to-date coverage of those
> topics, whereas blog posts sometimes grow stale over the years as nobody
> is interested in updating them.

To advocate your advocate, does the book content really stay so
up-to-date? (I have no experience with that repo, so I really don't
know.) An advantage of blog posts is that they come with a date and so
users can judge for themselves how stale it is or is not. In fact I
think it'd be odd to see reviews to update a blog post that's a few
years old; if the content is so different I'd expect to see a brand new
post and an editor's note on the top of the old one pointing forward, or
at least marking it as obsolete.

If it's a concept that's so specific that it really will stale out
quickly (e.g. exactly how to use git worktree down to the commands
without much context) vs. a higher level concept (how does git worktree
work and conceptually how do you use it) then it probably does belong in
the manpage or book. But I suppose I envision these types of posts doing
the latter, instead. Hmmmmm.

Maybe it's enough to say during review, "This seems like a good
candidate to move to manual/tutorial/git-scm book".

> 
> One downside is that it may be more annoying to try to integrate content
> into the existing structure of the book. Another is that a blog is
> something people subscribe to, so a post may generate attention/interest
> in a topic (but nobody wants to see a feed of book updates!). A prime
> example is something like a highlight of features after a new release,
> which is not book content at all, and just serves to generate attention.
> :)
> 
> So I don't think I'm really seriously suggesting this as an alternative,
> but maybe something to ponder.
> 
> > It could make sense to review contributions like this on the mailing
> > list, so that we get the attention of those who wrote the features
> > that are being covered in the blog posts - are we okay with the
> > additional traffic?
> 
> Additional traffic is fine. I do suspect that blog posts in particular
> would benefit from a more integrated review system like GitHub (or
> similar):
> 
>   - I'd expect there to be a lot of images, and those systems make
>     image diffs easy to see
> 
>   - the formatted output is going to be important to review; a
>     browser-based review system makes it easier to see the formatted
>     output (especially if they're written in markdown)
> 
>   - we're more likely to get/want drive-by fixes like typo corrections,
>     so reducing friction for non-regular contributors is more important
> 
> Obviously you can apply many of the same mailing list vs web review
> arguments that we've already had for writing Git itself (e.g., is
> reviewing formatted output much different than looking at the output of
> a compiled program?). But I think the nature of blog posts pushes it a
> bit further towards web-based review.

I follow, especially re formatted output and images, but I also don't
want to provide too much distance between the ML and these kinds of
posts. I wonder if it makes sense to mandate use of GitGitGadget, and
accept review comments both on the ML and the PR?

> 
> -Peff

Re: RFC - Git Developer Blog

[James Ramsay]

On 6 Aug 2019, at 16:49, Emily Shaffer wrote:

> On Tue, Aug 06, 2019 at 09:20:52AM -0400, Jeff King wrote:
>> On Mon, Aug 05, 2019 at 06:49:35PM -0700, Emily Shaffer wrote:
>>
>>> Are folks interested in writing and reviewing this kind of content? 
>>> Any
>>> ideas for where we may be able to host (maybe git-scm)?
>>
>> I think it would make sense to have blog.git-scm.com (and .org) with
>> this content. I'd be happy to deal with the technical side of setting
>> the name up. I think it should live in a different repository than 
>> the
>> main site, though (which is an overly-messy Rails app).
>
> I'd certainly be happy with that setup if others agree, although the
> incorporation with Git Rev News sounds interesting too (I'll reply to
> that post also).
>

As volunteered yesterday at the Virtual Contributors' Summit, I have 
created a project on GitLab to start working on this 
https://gitlab.com/git-scm/blog. I hope to have a basic text centric 
implementation for feedback in the next few weeks. For now, all I've 
created is merge request with an empty Hugo site and automated deploys.

Those who would like to be added as maintainers, you should be able to 
Request Access using the link near the project name.

Peff, you mentioned Jason might have some designs or ideas with regards 
visuals. I'm happy to be put in touch directly or collaborate here.

Re: RFC - Git Developer Blog

[pedro rijo]

Just a minor question: since we have git-scm, pro-git, and git
translations in github, why not keep in the same place, under the same
organization? I just find it easier to find than having repos
scattered across different git hosting services

James Ramsay <james@jramsay.com.au> escreveu no dia sexta, 13/09/2019
à(s) 14:34:
>
> On 6 Aug 2019, at 16:49, Emily Shaffer wrote:
>
> > On Tue, Aug 06, 2019 at 09:20:52AM -0400, Jeff King wrote:
> >> On Mon, Aug 05, 2019 at 06:49:35PM -0700, Emily Shaffer wrote:
> >>
> >>> Are folks interested in writing and reviewing this kind of content?
> >>> Any
> >>> ideas for where we may be able to host (maybe git-scm)?
> >>
> >> I think it would make sense to have blog.git-scm.com (and .org) with
> >> this content. I'd be happy to deal with the technical side of setting
> >> the name up. I think it should live in a different repository than
> >> the
> >> main site, though (which is an overly-messy Rails app).
> >
> > I'd certainly be happy with that setup if others agree, although the
> > incorporation with Git Rev News sounds interesting too (I'll reply to
> > that post also).
> >
>
> As volunteered yesterday at the Virtual Contributors' Summit, I have
> created a project on GitLab to start working on this
> https://gitlab.com/git-scm/blog. I hope to have a basic text centric
> implementation for feedback in the next few weeks. For now, all I've
> created is merge request with an empty Hugo site and automated deploys.
>
> Those who would like to be added as maintainers, you should be able to
> Request Access using the link near the project name.
>
> Peff, you mentioned Jason might have some designs or ideas with regards
> visuals. I'm happy to be put in touch directly or collaborate here.
>


-- 
Obrigado,

Pedro Rijo

Re: RFC - Git Developer Blog

[James Ramsay]

On 13 Sep 2019, at 10:05, pedro rijo wrote:

> Just a minor question: since we have git-scm, pro-git, and git
> translations in github, why not keep in the same place, under the same
> organization? I just find it easier to find than having repos
> scattered across different git hosting services

It wasn't a technical reason, but a matter of me (and my employer 
GitLab) volunteering the time needed to get the blog project off the 
ground. In the context of the Virtual Git Contributors' Summit, folks 
seemed happy with using GitLab or any other service with a Git 
interface.

Re: RFC - Git Developer Blog

[Emily Shaffer]

On Tue, Sep 17, 2019 at 03:22:38PM -0400, James Ramsay wrote:
> On 13 Sep 2019, at 10:05, pedro rijo wrote:
> 
> > Just a minor question: since we have git-scm, pro-git, and git
> > translations in github, why not keep in the same place, under the same
> > organization? I just find it easier to find than having repos
> > scattered across different git hosting services
> 
> It wasn't a technical reason, but a matter of me (and my employer GitLab)
> volunteering the time needed to get the blog project off the ground. In the
> context of the Virtual Git Contributors' Summit, folks seemed happy with
> using GitLab or any other service with a Git interface.

I really appreciate you setting it up, James - the starting inertia is
one of the trickier bits of something like this :)

If we decide later down the road that we really feel the need to have
the site, book, translations, etc all in one place I think it'll be
pretty trivial to mirror/move/whatever. I'm just happy to have somewhere
to start!

 - Emily

Re: RFC - Git Developer Blog

[pedro rijo]

Thanks for the explanation James :) Just wanted to understand if there
was any strong reason. As Emily said, we can easily move/mirror if we
find the need.

Thanks for starting up this project! If you need any help let me know

Emily Shaffer <emilyshaffer@google.com> escreveu no dia terça,
17/09/2019 à(s) 20:32:
>
> On Tue, Sep 17, 2019 at 03:22:38PM -0400, James Ramsay wrote:
> > On 13 Sep 2019, at 10:05, pedro rijo wrote:
> >
> > > Just a minor question: since we have git-scm, pro-git, and git
> > > translations in github, why not keep in the same place, under the same
> > > organization? I just find it easier to find than having repos
> > > scattered across different git hosting services
> >
> > It wasn't a technical reason, but a matter of me (and my employer GitLab)
> > volunteering the time needed to get the blog project off the ground. In the
> > context of the Virtual Git Contributors' Summit, folks seemed happy with
> > using GitLab or any other service with a Git interface.
>
> I really appreciate you setting it up, James - the starting inertia is
> one of the trickier bits of something like this :)
>
> If we decide later down the road that we really feel the need to have
> the site, book, translations, etc all in one place I think it'll be
> pretty trivial to mirror/move/whatever. I'm just happy to have somewhere
> to start!
>
>  - Emily



-- 
Obrigado,

Pedro Rijo

Re: RFC - Git Developer Blog

[James Ramsay]

On 13 Sep 2019, at 9:29, James Ramsay wrote:

> Peff, you mentioned Jason might have some designs or ideas with 
> regards visuals. I'm happy to be put in touch directly or collaborate 
> here.

Peff, did you touch base with Jason on the designs?

I have some travel coming up which I hope will provide quality train 
time to work on this.

Re: RFC - Git Developer Blog

[Jeff King]

On Wed, Oct 23, 2019 at 06:36:25PM -0400, James Ramsay wrote:

> On 13 Sep 2019, at 9:29, James Ramsay wrote:
> 
> > Peff, you mentioned Jason might have some designs or ideas with regards
> > visuals. I'm happy to be put in touch directly or collaborate here.
> 
> Peff, did you touch base with Jason on the designs?
> 
> I have some travel coming up which I hope will provide quality train time to
> work on this.

I did, but I was a bit slow at keeping the conversation going. If you
have specific things to ask for, you might want to reply at:

  https://github.com/git/git-scm.com/pull/1179#issuecomment-537945151

-Peff