Repository and Documentation: Technical Discussion

[Kaspar Bumke]

Hi all,

So there seems to be a general agreement that we would like a public repository with a bug tracker and a form of community documentation. Most of our discussions seem to have spiralled into the technical details of these.

Git and Github seem to be mention a lot and I would cast my vote for Git as a version control software as well.

As for Github, I am not so sure. While it is a free service It's dedication to allow your tickets and wiki data to be exported at a later date has not been proven. The Github software is not open source.
If we use an open source repository, bugtracking and documentations system that we host ourselves it could make it easier to migrate to another system in the future (an XMOS hosted system for instance). I have already suggested services such as redmine.org and trac.edgewall.org.

It has been brought up that XMOS already has an (underused) wiki and we could drive effort to document the XC language and XMOS code on there.

Cheers,

Kaspar

[Al Wood]

On 21 November 2010 16:23, Kaspar Bumke <kaspar...@gmail.com> wrote:
> Hi all,
>
> So there seems to be a general agreement that we would like a public
> repository with a bug tracker and a form of community documentation. Most of
> our discussions seem to have spiralled into the technical details of these.
>
> Git and Github seem to be mention a lot and I would cast my vote for Git as
> a version control software as well.
>

+1 Git
+1 Github

> As for Github, I am not so sure. While it is a free service It's dedication
> to allow your tickets and wiki data to be exported at a later date has not
> been proven. The Github software is not open source.

Well not strictly true, Git is open source and so are things like
Jekyl (used for pages) so we could easily self host later if we needed
to, all of the key info is in the Git data anyhow right? On the other
hand why would we want to host it ourselves, that's a lot of
overhead/admin!

> If we use an open source repository, bugtracking and documentations system
> that we host ourselves it could make it easier to migrate to another system
> in the future (an XMOS hosted system for instance). I have already suggested
> services such as redmine.org and trac.edgewall.org.

Xmos had had their chance to host it and have not taken it, its now up to us.

Is there a git based bug tracking system, I'm sure there is, that
would make things simpler and keep everything portable.

>
> It has been brought up that XMOS already has an (underused) wiki and we
> could drive effort to document the XC language and XMOS code on there.
>

For xmos specific things use the xcore wiki, but for foundation source
code it should be pages based IMHO and kept in the same repository
i.e. Git.

> Cheers,
>
> Kaspar
>
>

--
http://www.folknology.com

[Kaspar Bumke]

How about the wiki feature of gitorious.org? How does it compare to github's pages?

[russ]

On Nov 21, 8:38 am, Al Wood <a...@folknology.com> wrote:
> On 21 November 2010 16:23, Kaspar Bumke <kaspar.bu...@gmail.com> wrote:> Hi all,

>
> > So there seems to be a general agreement that we would like a public
> > repository with a bug tracker and a form of community documentation. Most of
> > our discussions seem to have spiralled into the technical details of these.
>
> > Git and Github seem to be mention a lot and I would cast my vote for Git as
> > a version control software as well.
>
> +1 Git
> +1 Github

In order to have a group of members working on multiple projects we
should use an Organization
https://github.com/blog/674-introducing-organizations

I did produce this
https://github.com/XMOSCookbook
back in June. Quick to setup. I'd take it down if we make an XMOS
foundation organization, to avoid confusion.

>
> > As for Github, I am not so sure. While it is a free service It's dedication
> > to allow your tickets and wiki data to be exported at a later date has not
> > been proven. The Github software is not open source.
>
> Well not strictly true, Git is open source and so are things like
> Jekyl (used for pages) so we could easily self host later if we needed
> to, all of the key info is in the Git data anyhow right? On the other
> hand why would we want to host it ourselves, that's a lot of
> overhead/admin!

Yes. I agree on this point.
Github is a very practical choice. We can move to our own git repo at
some time but, IMHO, life is too short to worry about that. I used to
faithfully manage my own email servers (from 1991 to about 2008) but
can never imagine going back. I am phasing out my use of my own SVN.
Github is the answer, what was your question?

>
> > If we use an open source repository, bugtracking and documentations system
> > that we host ourselves it could make it easier to migrate to another system
> > in the future (an XMOS hosted system for instance). I have already suggested
> > services such as redmine.org and trac.edgewall.org.

I managed trac, too. I'm a python lover, so trac is a fave of mine,
but I need to focus away from infrastructure, and onto results.

>
> Xmos had had their chance to host it and have not taken it, its now up to us.

Agree, except that I'd love to be working in the same repo as XMOS, so
let's not close any doors.

>
> Is there a git based bug tracking system, I'm sure there is, that
> would make things simpler and keep everything portable.

I'd like to use issues on github. they attach to the projects, and can
refer to revisions.

>
>
>
> > It has been brought up that XMOS already has an (underused) wiki and we
> > could drive effort to document the XC language and XMOS code on there.
>
> For xmos specific things use the xcore wiki, but for foundation source
> code it should be pages based IMHO and kept in the same repository
> i.e. Git.

Yes. I agree.
In other projects (I'm thinking of the many python-based things I work
on) we make executable documentation, which is narrative style, but
can be run through the test system. If you change an api, your
documentation flags an error, so you ensure that everything stays up
to date...
This is not going to happen in XC anytime soon (ever!), but the
principle is important. Documentation near to code, and wherever
possible in the same repository.

So here is an example where the documentation is in the code repo, and
is executed as part of the tests. It also is intended to map to an
HTML template at PYPI, so it's very browser friendly.
http://pypi.python.org/pypi/topia.termextract/

There may be things we can do with our XC/C projects along these
lines.

>
> > Cheers,
>
> > Kaspar
>
> --http://www.folknology.com

[Al Wood]

As far as source code documentation goes Doxygen seems to be popular
http://www.stack.nl/~dimitri/doxygen/ any thoughts?

>>
>> > Cheers,
>>
>> > Kaspar
>>
>> --http://www.folknology.com
>

--
http://www.folknology.com

[russ]

On Nov 21, 11:10 am, Al Wood <a...@folknology.com> wrote:
>
> As far as source code documentation goes Doxygen seems to be popularhttp://www.stack.nl/~dimitri/doxygen/any thoughts?
>

Could work. I used it a while back successfully.

in general, if headers and sources become too cluttered it breaks
readability for reading code on github/whatever. I really like what we
do in python, but that's not going to work in the C-like space. :(

[Kaspar Bumke]

I had a go at setting up Redmine on my VPS. Set-up was pretty straightforward but did require a bit of research. It runs terrible as it requires more RAM than I can offer it. Not something for a low-end-box like mine. Generally I would say that the time effort and money required for this solution do not outweigh the benefit of autonomy.

[Kaspar Bumke]

I grew rather fond of Doxygen when I was working with the ffmpeg source code. How well would this tie in with Github pages though?