Re: Poject bootstraping script in Developer Guide

[Mohammed Elzubeir <elzubeir at arabeyes dot org>]

On Mon, 2004-04-05 at 21:12, Muhammad Alkarouri wrote:

> Huh? Elzubeir didn't do that, at least in public. I don't think that
> committing a new version of developer guide to CVS is a public
> announcement.
> The developer guide at the site is still at revision 1.3. No
> announcement for the new version happened.
> 

Documents are daily generated from CVS -- so whatever is committed to
CVS eventually shows up on the website within a max of 24 hours. Perhaps
I should have made an announcement, but I was under the impression the
changes were discussed in the past.

> I believe we all have the right to argue. Otherwise the resulting
> document should not be binding.
> 

s/argue/discuss ? ;)

> Alas, my discussion about compatibility with the current numbering has
> not even warrented a reply. If that was so stupid, please tell me so.
> 

Has it not? My bad. The only modification I made to the versioning
scheme is as per Behdad's suggestion, after the BiCon re-release. The
issue has been discussed previously and I am again (as I remember my
responses being) against leaving it to the developer to decide on the
versioning scheme. Again, this was _the_ primary reason the entire
Developer Guide was written.

> Another point, Behdad. As long as there is a standard or a decision
> already taken we should abide by it. If it needs a change we need some
> discussion, or at least a notification before changing.
> The Makefile.cvs existing in the bicon cvs was not in anybody's way, I
> think, so you needn't have removed it before explaining your point.
> Especially that the 'will be' developer's guide did not give us a
> ./bootstrap option, without a Makefile.cvs/autogen.sh.
> 

I had no intentions of turning this bootstrapping issue into a
controversial issue. What is really important to me is that
autogenerated files are not in CVS. How you deal with it (boostrap,
autogen.sh, Makefile.cvs -- is something I don't want to go to war
over). 

I think I will elaborate about this in the guide and leave it up to the
developer to decide how to best proceed.

> In other words, contributions to existing external projects should
> conform to the relevent coding standards, rather than Arabeyes'.
> 

Not necessarily this way. Bayani is a Qt-based project -- it is not an
'external' project. However, I would think that it probably should
comply with the Qt norms, etc.

> > And now the documentation:
> > 
> > 5. Project Documentation:
> > 
> >   * Well, many people like RCS headers, that doesn't look bad,
> > but I don't think it should be a mandatory thing either.
> 
> Second that.
> 

I'm sticking to my guns on this one. I don't think it's hurting anyone.

> > 
> >   * Doxygen style source code doc:  Many projects simply do not
> > accept Doxygen.  GNOME people have their own system which is very
> > similar to Doxygen.  Donno about KDE.  But again, Java and Python
> > have their own systems.  And I myself am lasier than doing
> > Doxygen.
> > 
> 
> Also speaking about other standards. I definitely prefer to use python
> documentation style when using python. Contributions to external
> projects should also conform to the relevant standards.
> 

Perhaps I should reconsider this whole Doxygen thing since everyone's up
and fighting against it. The point of the Guide is not to enforce rules
that _I_ want -- it is to establish a standard across Arabeyes. I keep
repeating this because I do get the feeling that some people may believe
otherwise. 

Would it be acceptable to say, _every_ method/function MUST be
documented in the code in whatever documentation scheme that
language/toolset that project depends on and that Doxygen would be the
default (if none exists)?

> >   * Manpages:  They are old and being kinda deprecated.  The
> > format is evil and other stuff.  Many (GNU) recommends info
> > pages, but they are not necessarily easier to write.  For
> > example, GNU FriBidi is asked to have info pages instead of man.
> 
> Man pages are old, but they have not been _successfully_ deprecated (if
> you get what I mean). I wouldn't require info pages as a must, a mention
> is probably worth it.
> 

Yes, the FSF is weird like that. I don't care much for info pages but
hey, if you want to have info pages it's up to you. I can for instance
say you must have one or the other. The point is, _some_ form of
documentation is a MUST prior to a release. Whether it is in info or man
format is insignificant to me. I'm not sure how others feel about it. 

> 
> Sorry everyone for that long message about a subject that has already
> been discussed before. Specially as it seems that discussion now is
> futile.

Well, it keeps popping up ;) And here, I am replying to YOU! ;)

Regards,
Mohammed Elzubeir