[gentoo-dev] Merging the devrel handbook into the devmanual

[gentoo-dev] Merging the devrel handbook into the devmanual

[Michael Palimaka]

Hi all,

In bug #304435[1], hwoarang suggested merging the devrel handbook[2] 
into the devmanual[3].

As the project has grown, so has the amount - and dispersion - of 
development information. I believe consolidation of this information 
into a single point will make everyone's (especially new developers) 
lives easier.

What do you think?

Best regards,
Michael

[1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
[2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
[3]: http://devmanual.gentoo.org/

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Sergey Popov]

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

31.10.2012 16:39, Michael Palimaka пишет:
> Hi all,
>
> In bug #304435[1], hwoarang suggested merging the devrel handbook[2]
> into the devmanual[3].
>
> As the project has grown, so has the amount - and dispersion - of
> development information. I believe consolidation of this information
> into a single point will make everyone's (especially new developers)
> lives easier.
>
> What do you think?
>
> Best regards,
> Michael
>
> [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
> [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
> [3]: http://devmanual.gentoo.org/
>
As a new developer , I think this is a good idea. When i was a recruit
it was not so easy to find some information(well, at least for me). Now
i am more familiar with Gentoo website internals and it's not a problem
anymore(at least, generally :-)). I think recruiters would be also
agreed with this point of view(at least hwoarang does :-D)

-- 
Best regards, Sergey Popov
Gentoo Linux Developer
Desktop-effects project lead



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 554 bytes --]

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Dirkjan Ochtman]

On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensington@gentoo.org> wrote:
> What do you think?

+1 love it. The split is pretty annoying, it would be great to have
everything in one place.

Cheers,

Dirkjan

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Diego Elio Pettenò]

On 31/10/2012 05:39, Michael Palimaka wrote:
> 
> 
> In bug #304435[1], hwoarang suggested merging the devrel handbook[2]
> into the devmanual[3].

+1 it was on my TODO list for over two years at this point.

-- 
Diego Elio Pettenò — Flameeyes
flameeyes@flameeyes.eu — http://blog.flameeyes.eu/

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Theo Chatzimichos]

On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensington@gentoo.org> wrote:
> Hi all,
>
> In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
> the devmanual[3].
>
> As the project has grown, so has the amount - and dispersion - of
> development information. I believe consolidation of this information into a
> single point will make everyone's (especially new developers) lives easier.
>
> What do you think?
>
> Best regards,
> Michael
>
> [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
> [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
> [3]: http://devmanual.gentoo.org/

+1 and btw move the devmanual in the wiki :D

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Ciaran McCreesh]

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

On Wed, 31 Oct 2012 17:26:38 +0100
Theo Chatzimichos <tampakrap@gentoo.org> wrote:
> +1 and btw move the devmanual in the wiki :D

That would rather go against the original idea behind the devmanual,
which was that it was supposed to be high quality and authoritative.

-- 
Ciaran McCreesh

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

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Michael Mol]

On Wed, Oct 31, 2012 at 3:02 PM, Ciaran McCreesh
<ciaran.mccreesh@googlemail.com> wrote:
>
> On Wed, 31 Oct 2012 17:26:38 +0100
> Theo Chatzimichos <tampakrap@gentoo.org> wrote:
> > +1 and btw move the devmanual in the wiki :D
>
> That would rather go against the original idea behind the devmanual,
> which was that it was supposed to be high quality and authoritative.
>
Pages can be locked to be editable only by members of blessed groups.

--
:wq

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Markos Chandras]

On Wed, Oct 31, 2012 at 7:02 PM, Ciaran McCreesh
<ciaran.mccreesh@googlemail.com> wrote:
> On Wed, 31 Oct 2012 17:26:38 +0100
> Theo Chatzimichos <tampakrap@gentoo.org> wrote:
>> +1 and btw move the devmanual in the wiki :D
>
> That would rather go against the original idea behind the devmanual,
> which was that it was supposed to be high quality and authoritative.
>
> --
> Ciaran McCreesh

Yes, I see no point moving it to wiki. We want to move it to a more
modern format and we want to keep it in
VCS so others can send pull requests, submit nice patches or have
separate branches if needed.

-- 
Regards,
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Michał Górny]

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

On Wed, 31 Oct 2012 17:26:38 +0100
Theo Chatzimichos <tampakrap@gentoo.org> wrote:

> On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensington@gentoo.org> wrote:
> > Hi all,
> >
> > In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
> > the devmanual[3].
> >
> > As the project has grown, so has the amount - and dispersion - of
> > development information. I believe consolidation of this information into a
> > single point will make everyone's (especially new developers) lives easier.
> >
> > What do you think?
> >
> > Best regards,
> > Michael
> >
> > [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
> > [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
> > [3]: http://devmanual.gentoo.org/
> 
> +1 and btw move the devmanual in the wiki :D

I'm not sure if wiki fits nicely here. I believe that wiki is very
useful at taking notes, writing quick guides and sharing information
and tips in general. The main advantage is the free workflow -- you
have an idea to share but can't do it all by yourself. You start it,
others can easily improve it.

Sadly, our wiki is MediaWiki. Not getting deep into it, the syntax is
worse than awful. It could be considered acceptable if you write
encyclopedia articles, stuff with heavy inside linking and not much
code inside. However, for technical articles it is horrible, horrible
and once more horrible.

Shortly saying, devmanual in wiki would mostly consist of HTML tagsoup
intermixed with wiki text. For the very simple reason that MediaWiki
lags markup for as basic things as inline code and requires you to use
HTML instead. Not something I'd use for anything as fundamental
as devmanual.

-- 
Best regards,
Michał Górny

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

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Michael Mol]

On Thu, Nov 1, 2012 at 5:34 PM, Michał Górny <mgorny@gentoo.org> wrote:
> On Wed, 31 Oct 2012 17:26:38 +0100
> Theo Chatzimichos <tampakrap@gentoo.org> wrote:
>
>> On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka <kensington@gentoo.org> wrote:
>> > Hi all,
>> >
>> > In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
>> > the devmanual[3].
>> >
>> > As the project has grown, so has the amount - and dispersion - of
>> > development information. I believe consolidation of this information into a
>> > single point will make everyone's (especially new developers) lives easier.
>> >
>> > What do you think?
>> >
>> > Best regards,
>> > Michael
>> >
>> > [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
>> > [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
>> > [3]: http://devmanual.gentoo.org/
>>
>> +1 and btw move the devmanual in the wiki :D
>
> I'm not sure if wiki fits nicely here. I believe that wiki is very
> useful at taking notes, writing quick guides and sharing information
> and tips in general. The main advantage is the free workflow -- you
> have an idea to share but can't do it all by yourself. You start it,
> others can easily improve it.
>
> Sadly, our wiki is MediaWiki. Not getting deep into it, the syntax is
> worse than awful. It could be considered acceptable if you write
> encyclopedia articles, stuff with heavy inside linking and not much
> code inside. However, for technical articles it is horrible, horrible
> and once more horrible.
>
> Shortly saying, devmanual in wiki would mostly consist of HTML tagsoup
> intermixed with wiki text. For the very simple reason that MediaWiki
> lags markup for as basic things as inline code and requires you to use
> HTML instead. Not something I'd use for anything as fundamental
> as devmanual.

Rosetta Code (my site) runs MediaWiki. I can attest to the terrible
thing that is MW syntax. That said, we did ultimately come up with
workarounds for 98% of the problems. (Most of the remaining 2% are
spammers...and that comes down to a question of strongly you lock the
thing down.)

I've submitted patches to Gentoo docs before. Honestly, I found it a
pain; I'm not accustomed to that particular process. Admittedly, this
is one of those cases where I simply lack an attainable skill.

If nothing else, I'd love to see the docs all reside in Git; I could
fork to my Github account and generate pull requests from there. A
proper maintainer could review the pull request and decide whether or
not to merge it. That would be a much more comfortable workflow, IMO.
(Heck, I wouldn't mind migrating RC to a similar workflow; I'd just
have to migrate gigabytes worth of wikitext history to a format with
new semantics...)

--
:wq

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Michał Górny]

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

On Thu, 1 Nov 2012 17:42:52 -0400
Michael Mol <mikemol@gmail.com> wrote:

> On Thu, Nov 1, 2012 at 5:34 PM, Michał Górny <mgorny@gentoo.org> wrote:
> > Shortly saying, devmanual in wiki would mostly consist of HTML tagsoup
> > intermixed with wiki text. For the very simple reason that MediaWiki
> > lags markup for as basic things as inline code and requires you to use
> > HTML instead. Not something I'd use for anything as fundamental
> > as devmanual.
> 
> Rosetta Code (my site) runs MediaWiki. I can attest to the terrible
> thing that is MW syntax. That said, we did ultimately come up with
> workarounds for 98% of the problems. (Most of the remaining 2% are
> spammers...and that comes down to a question of strongly you lock the
> thing down.)

Do you believe that the effort was worth it? As far as I can see, you
worked around issues with a particularly bad software for your use.
Instead, you could work on a good piece of software which could help
others.

> I've submitted patches to Gentoo docs before. Honestly, I found it a
> pain; I'm not accustomed to that particular process. Admittedly, this
> is one of those cases where I simply lack an attainable skill.

I'm not saying that our XML forks are good. I'd honestly just use
reStructuredText which is basically 'good enough' to write articles
efficiently while keeping them readable.

> If nothing else, I'd love to see the docs all reside in Git; I could
> fork to my Github account and generate pull requests from there. A
> proper maintainer could review the pull request and decide whether or
> not to merge it. That would be a much more comfortable workflow, IMO.
> (Heck, I wouldn't mind migrating RC to a similar workflow; I'd just
> have to migrate gigabytes worth of wikitext history to a format with
> new semantics...)

Yes, considering the development of modern git solutions, old wikis
could be at least partially replaced by it. I think the github wikis
are the best example here, with their best feature being the ability to
choose markup yourself (however, to be honest, some of the markups
aren't implemented really well there).

However, that's the only thing which github did quite good. The quality
of forking and pull requests on github are a whole different story,
and something not really suited for real-life workflow. In that case,
bitbucket is definitely superior to them.

-- 
Best regards,
Michał Górny

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

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Petteri Räty]

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

On 31.10.2012 14.39, Michael Palimaka wrote:
> Hi all,
> 
> In bug #304435[1], hwoarang suggested merging the devrel handbook[2]
> into the devmanual[3].
> 
> As the project has grown, so has the amount - and dispersion - of
> development information. I believe consolidation of this information
> into a single point will make everyone's (especially new developers)
> lives easier.
> 
> What do you think?
> 

I think you will only find people who support the idea. Some years back
I tried to list people to migrate information on the basis of for
example one page per developer but the actual contributions didn't
amount to much. Let's hope there's renewed energy on this front.

Regards,
Petteri



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 894 bytes --]

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Markos Chandras]

On Thu, Nov 1, 2012 at 2:48 PM, Petteri Räty <betelgeuse@gentoo.org> wrote:
> On 31.10.2012 14.39, Michael Palimaka wrote:
>> Hi all,
>>
>> In bug #304435[1], hwoarang suggested merging the devrel handbook[2]
>> into the devmanual[3].
>>
>> As the project has grown, so has the amount - and dispersion - of
>> development information. I believe consolidation of this information
>> into a single point will make everyone's (especially new developers)
>> lives easier.
>>
>> What do you think?
>>
>
> I think you will only find people who support the idea. Some years back
> I tried to list people to migrate information on the basis of for
> example one page per developer but the actual contributions didn't
> amount to much. Let's hope there's renewed energy on this front.
>
> Regards,
> Petteri
>
>

There is :)
I will create a separate branch tonight so whoever is interested can
start working on it.

-- 
Regards,
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Markos Chandras]

On Wed, Oct 31, 2012 at 12:39 PM, Michael Palimaka
<kensington@gentoo.org> wrote:
> Hi all,
>
> In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
> the devmanual[3].
>
> As the project has grown, so has the amount - and dispersion - of
> development information. I believe consolidation of this information into a
> single point will make everyone's (especially new developers) lives easier.
>
> What do you think?
>
> Best regards,
> Michael
>
> [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
> [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
> [3]: http://devmanual.gentoo.org/
>

fyi

http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=shortlog;h=refs/heads/devrel-handbook

-- 
Regards,
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Ben de Groot]

On 4 November 2012 05:15, Markos Chandras <hwoarang@gentoo.org> wrote:
> On Wed, Oct 31, 2012 at 12:39 PM, Michael Palimaka
> <kensington@gentoo.org> wrote:
>> Hi all,
>>
>> In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
>> the devmanual[3].
>>
>> As the project has grown, so has the amount - and dispersion - of
>> development information. I believe consolidation of this information into a
>> single point will make everyone's (especially new developers) lives easier.
>>
>> What do you think?
>>
>> Best regards,
>> Michael
>>
>> [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
>> [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
>> [3]: http://devmanual.gentoo.org/
>>
>
> fyi
>
> http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=shortlog;h=refs/heads/devrel-handbook
>

That's a good start. I would like to see our devmanual become the
one-stop-shop solution for anything regarding development policies
that a Gentoo dev (or overlay maintainer) needs to know. That would
mean a recruit would find everything he needs in the devmanual — or at
least he would find references to other important documents (e.g.
GLEPs, PMS, eclass manpages) in case not all relevant information is
contained in the devmanual. That way everything an aspiring Gentoo dev
needs to know can be found in one place, instead of having to go
hunting through many dispersed sources.

This also means we should document all QA policies, project/herd/arch
specific policies, development-related council decisions, and
(possibly unwritten) best practices in our devmanual. I think that
would make things much easier for all of us.

Obviously I am willing to do my part to make this happen.
-- 
Cheers,

Ben | yngwin
Gentoo developer
Gentoo Qt project lead, Gentoo Wiki admin

Re: [gentoo-dev] Merging the devrel handbook into the devmanual

[Markos Chandras]

On Sun, Nov 4, 2012 at 4:47 AM, Ben de Groot <yngwin@gentoo.org> wrote:
> On 4 November 2012 05:15, Markos Chandras <hwoarang@gentoo.org> wrote:
>> On Wed, Oct 31, 2012 at 12:39 PM, Michael Palimaka
>> <kensington@gentoo.org> wrote:
>>> Hi all,
>>>
>>> In bug #304435[1], hwoarang suggested merging the devrel handbook[2] into
>>> the devmanual[3].
>>>
>>> As the project has grown, so has the amount - and dispersion - of
>>> development information. I believe consolidation of this information into a
>>> single point will make everyone's (especially new developers) lives easier.
>>>
>>> What do you think?
>>>
>>> Best regards,
>>> Michael
>>>
>>> [1]: https://bugs.gentoo.org/show_bug.cgi?id=304435
>>> [2]: http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml
>>> [3]: http://devmanual.gentoo.org/
>>>
>>
>> fyi
>>
>> http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=shortlog;h=refs/heads/devrel-handbook
>>
>
> That's a good start. I would like to see our devmanual become the
> one-stop-shop solution for anything regarding development policies
> that a Gentoo dev (or overlay maintainer) needs to know. That would
> mean a recruit would find everything he needs in the devmanual — or at
> least he would find references to other important documents (e.g.
> GLEPs, PMS, eclass manpages) in case not all relevant information is
> contained in the devmanual. That way everything an aspiring Gentoo dev
> needs to know can be found in one place, instead of having to go
> hunting through many dispersed sources.
>
> This also means we should document all QA policies, project/herd/arch
> specific policies, development-related council decisions, and
> (possibly unwritten) best practices in our devmanual. I think that
> would make things much easier for all of us.
>
> Obviously I am willing to do my part to make this happen.
> --
> Cheers,
>
> Ben | yngwin
> Gentoo developer
> Gentoo Qt project lead, Gentoo Wiki admin
>

The ETA for the merge is this weekend. If you have a guide/document
that links to the devrel ebuild HOWTO[1] please fix your links as the
devrel handbook (the ebuild stuff for now) is completely going away
and not marked as deprecated.

[1] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=1

-- 
Regards,
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2