[gentoo-doc] Documentation/website in git?

[gentoo-doc] Documentation/website in git?

[Peter Volkov]

Hi, guys. While there is some job required to move portage tree into git
it looks like moving documentation and web-site could be done much
easier. Are there any plans to move on git? Was anything done in this
direction? This will simplify translator's job as we are planning to use
git that makes commits faster and allows us to ease workflow.

-- 
Peter.

Re: [gentoo-doc] Documentation/website in git?

[Tobias Heinlein]

Peter Volkov wrote, on 09/16/2010 06:46 PM:
> Hi, guys. While there is some job required to move portage tree into git
> it looks like moving documentation and web-site could be done much
> easier.

Yeah, git++.

> Are there any plans to move on git? Was anything done in this
> direction? This will simplify translator's job as we are planning to use
> git that makes commits faster and allows us to ease workflow.

Who is "we" in this case? The translators? If yes, has there been some
discussion?

Also, how exactly does it ease workflow? Is there something specific for
translating stuff that CVS can't do?

Re: [gentoo-doc] Documentation/website in git?

[Peter Volkov]

В Сбт, 18/09/2010 в 21:34 +0200, Tobias Heinlein пишет:
> Peter Volkov wrote, on 09/16/2010 06:46 PM:
> > Hi, guys. While there is some job required to move portage tree into git
> > it looks like moving documentation and web-site could be done much
> > easier.
> 
> Yeah, git++.
> 
> > Are there any plans to move on git? Was anything done in this
> > direction? This will simplify translator's job as we are planning to use
> > git that makes commits faster and allows us to ease workflow.
> 
> Who is "we" in this case? The translators? If yes, has there been some
> discussion?

Yes, translators. And there was no discussion yet. Grand plan is to use
transifex and everything more or less works (testing version is on
transifex.gentoo.ru) but we are going to move on transifex.net and
update everything for upcoming transifex-1.x. Once done we'll announce
this since we'll need to attract translators and I guess this experience
could be of interest for others too.

> Also, how exactly does it ease workflow? Is there something specific for
> translating stuff that CVS can't do?

We need branches (for workflow - one for translators and one for
editors) and speed (it's pain to use CVS history to see changes) and too
many problems we are all well aware about :) CVS has no advantages for
documentation so may be we just move gentoo repository on git?

-- 
Peter.

Re: [gentoo-doc] Documentation/website in git?

[Tobias Heinlein]

Peter Volkov wrote, on 09/19/2010 01:37 PM:
> Yes, translators. And there was no discussion yet. Grand plan is to use
> transifex and everything more or less works (testing version is on
> transifex.gentoo.ru) 

transifex looks promising, but it uses gettext/.po files. How does that
work for our GuideXML stuff? Do you convert them manually?

Re: [gentoo-doc] Documentation/website in git?

[Peter Volkov]

В Вск, 19/09/2010 в 14:47 +0200, Tobias Heinlein пишет:
> Peter Volkov wrote, on 09/19/2010 01:37 PM:
> > Yes, translators. And there was no discussion yet. Grand plan is to use
> > transifex and everything more or less works (testing version is on
> > transifex.gentoo.ru) 
> 
> transifex looks promising, but it uses gettext/.po files. How does that
> work for our GuideXML stuff? Do you convert them manually?

This is done with customized xml2po script. For that you need to grab
xml2po-gentoo from Azamat's overlay [1]. po files are semi-manually
generated at the moment but it's possible to run cron for that. Makefile
for transition is here [2].

[1] http://github.com/winterheart/iceland
[2] http://git.gentoo.ru/gentoo-doc-doc/tree/

BTW, all cookies should be sent to Azamat :)

-- 
Peter.

Re: [gentoo-doc] Documentation/website in git?

[Joshua Saddler]

[-- Attachment #1: Type: text/plain, Size: 2929 bytes --]

On Thu, 16 Sep 2010 20:46:52 +0400
Peter Volkov <pva@gentoo.org> wrote:
> Hi, guys. While there is some job required to move portage tree
> into git it looks like moving documentation and web-site could be
> done much easier. Are there any plans to move on git? Was anything
> done in this direction? This will simplify translator's job as we
> are planning to use git that makes commits faster and allows us to
> ease workflow.

I've been talking to Robin (robbat2) off and on about moving to git
for more than a year now. From what he tells me, it's a simple thing
to switch our website and docs over to git, on the infrastructure
side at least.

There aren't too many changes to make to the docs scripts that gorg
runs, and there's no difference in server load or required storage.

However, we would need to completely rethink our workflow. I jotted
down some notes many months ago; I still have some of 'em:

- Bugzilla changes for drafts and patches? How much would still be
  posted there when we could just have people send pull requests to
  their git clones of our master?
- What about branching? Needed for what we do? What about the
  handbooks? (We used to always do something like that for the
  networkless handbooks, which is partly why we no longer keep
  versioned handbooks around.)
- Reverting commits should be simpler. CVS sucks for reverting
  mistakes.
- Internal doc formatting: should we abandon the <version> scheme,
  since we can just use git commit hashes? It would reduce the manual
  bumping we do (and forget to do). How would that work with git
  history?
- Speaking of history: we'd need a way to carry over CVS history to
  Git history; we absolutely CANNOT lose the merge/update history, or
  all the docs that are in and out of the CVS "attic." Often enough
  we get bugs asking for additions or changes, but it's been settled
  and explained in previous commits and CVS logs.
- Cloning and initial checkouts could be quite nice for translators
  and English devs alike; merging branches and managing contributors
  would be much more flexible and fine-grained. We could host all
  clones on gentoo's git, or even if we continue to have multiple
  separate repos, git makes it easy to pull and merge those changes
  regardless of location.
- What else would translators need?

Git access will ultimately require "gitolite" to be ready. Gitolite
is a perl-based replacement for gitosis-gentoo, which serves up all
our git trees ATM.

I wouldn't mind moving to git, but I already have some limited
experience using it for a year or so. Not all of our contributors are
familiar with it, and even I need to learn more about how git works,
since it's so different from CVS. I imagine we might have some
holdouts who don't want to move from CVS at all, so now's the time to
speak up. What does the rest of the GDP think about moving to git?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-doc] Documentation/website in git?

[Jan Kundrát]

Joshua Saddler wrote:
> - Bugzilla changes for drafts and patches? How much would still be
>   posted there when we could just have people send pull requests to
>   their git clones of our master?

I have no preference, but would recommend to follow the rest of Gentoo 
projects.

> - What about branching? Needed for what we do? What about the
>   handbooks? (We used to always do something like that for the
>   networkless handbooks, which is partly why we no longer keep
>   versioned handbooks around.)

I can't see how using Git branches would reduce the work here, though -- 
you still have to write the patches (English text is much less 
structured than C code, so you likely won't be able to make use of

> - Internal doc formatting: should we abandon the <version> scheme,
>   since we can just use git commit hashes? It would reduce the manual
>   bumping we do (and forget to do). How would that work with git
>   history?

No, we can't abandon that for the same reason why we do not use CVS 
keywords or anything. Content change is to be determined by the 
author/committer, not by the simple fact that "someone changed that file".

> - Speaking of history: we'd need a way to carry over CVS history to
>   Git history; we absolutely CANNOT lose the merge/update history, or
>   all the docs that are in and out of the CVS "attic." Often enough
>   we get bugs asking for additions or changes, but it's been settled
>   and explained in previous commits and CVS logs.

That's the usual case when migrating between VCSes, history is always kept.

> - Cloning and initial checkouts could be quite nice for translators
>   and English devs alike; merging branches and managing contributors
>   would be much more flexible and fine-grained. We could host all
>   clones on gentoo's git, or even if we continue to have multiple
>   separate repos, git makes it easy to pull and merge those changes
>   regardless of location.

In fact, any modern VCS is better than CVS. You'd no longer have to do 
SSH tricks in order to get a decent performance from CVS (it likes to 
establish a fresh connection for each file, IIRC).

> Git access will ultimately require "gitolite" to be ready. Gitolite
> is a perl-based replacement for gitosis-gentoo, which serves up all
> our git trees ATM.

Is that infra's requirement? From a POV of a GDP member and a 
translator, I couldn't care less about what is used on the web for git 
browsing.

> I wouldn't mind moving to git, but I already have some limited
> experience using it for a year or so. Not all of our contributors are
> familiar with it, and even I need to learn more about how git works,
> since it's so different from CVS. I imagine we might have some
> holdouts who don't want to move from CVS at all, so now's the time to
> speak up. What does the rest of the GDP think about moving to git?

In my opinion, we should go for it.

Cheers,
-jkt
-- 
cd /local/pub && more beer > /dev/mouth