Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Sun, Nov 4, 2012 at 4:47 AM, Ben de Groot wrote: > On 4 November 2012 05:15, Markos Chandras wrote: >> On Wed, Oct 31, 2012 at 12:39 PM, 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? >>> >>> 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
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On 4 November 2012 05:15, Markos Chandras wrote: > On Wed, Oct 31, 2012 at 12:39 PM, 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? >> >> 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
On Wed, Oct 31, 2012 at 12:39 PM, 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? > > 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
On Thu, 1 Nov 2012 17:42:52 -0400 Michael Mol wrote: > On Thu, Nov 1, 2012 at 5:34 PM, Michał Górny 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 signature.asc Description: PGP signature
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Thu, Nov 1, 2012 at 5:34 PM, Michał Górny wrote: > On Wed, 31 Oct 2012 17:26:38 +0100 > Theo Chatzimichos wrote: > >> On Wed, Oct 31, 2012 at 1:39 PM, 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? >> > >> > 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
On Wed, 31 Oct 2012 17:26:38 +0100 Theo Chatzimichos wrote: > On Wed, Oct 31, 2012 at 1:39 PM, 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? > > > > 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 signature.asc Description: PGP signature
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Thu, Nov 1, 2012 at 2:48 PM, Petteri Räty 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
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 signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Wed, Oct 31, 2012 at 7:02 PM, Ciaran McCreesh wrote: > On Wed, 31 Oct 2012 17:26:38 +0100 > Theo Chatzimichos 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
On Wed, Oct 31, 2012 at 3:02 PM, Ciaran McCreesh wrote: > > On Wed, 31 Oct 2012 17:26:38 +0100 > Theo Chatzimichos 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
On Wed, 31 Oct 2012 17:26:38 +0100 Theo Chatzimichos 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 signature.asc Description: PGP signature
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Wed, Oct 31, 2012 at 1:39 PM, 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? > > 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
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 flamee...@flameeyes.eu — http://blog.flameeyes.eu/
Re: [gentoo-dev] Merging the devrel handbook into the devmanual
On Wed, Oct 31, 2012 at 1:39 PM, Michael Palimaka 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
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 signature.asc Description: OpenPGP digital signature
[gentoo-dev] Merging the devrel handbook into the devmanual
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/
