Lack of informative files in FreeBSD svn

[Mehmet Erol Sanliturk]

On Sun, Nov 9, 2014 at 8:32 PM, John-Mark Gurney <jmg at funkthat.com> wrote:

> Mehmet Erol Sanliturk wrote this message on Sun, Nov 09, 2014 at 07:27
> -0800:
> > When the FreeBSD svn is studied , one of the most important problems
> seems
> > to be missing ReadMe or other informative files in many directories .
>
> If we put a README in every directory, we'd end up w/ over 6k READMEs,
> and that's just for base... We'd end up w/ 100 times more if we did
> that for all of projects and users in svn...  The svn tree isn't
> a stand alone product...  Did you download the doc svn repo too?
>
> > The assumption at present seems to be that such a study will ALWAYS be
> > performed by persons who know the FreeBSD very well .
>
> I'd disagree...  the Developers Handbook mentioned below is an example
> of that...
>
> > This structure is , in my opinion , an important obstacle in front of the
> > persons wishing to study and understand the FreeBSD structure very well
> and
> > then try to make contributions .
> >
> >
> > As an example , consider
> >
> > https://svnweb.freebsd.org/base/user/
> >
> > directory .
> >
> > In that directory , there are work in progress projects ( I assume like
> > that ) .
> > There is a guidelines text , but not a ReadMe file or any other named
> file
> > to list names and their project subjects .
>
> You need to talk to each user to which the repo belongs...  Most of
> these are not for public consumption, unless the user calls for
> testing...
>
> > Also there is no any html file which contains links to related off site
> > pages such as FreeBSD wiki .
> >
> > And also no one of the directories contain a ReadMe file about the tasks
> > studied .
> >
> >
> > It may be said that , no one of the directory is related to the general
> > public other than its owner .
> >
> > Such an idea is very contrary to ideas specified in status reports and
> open
> > projects pages and in some other messages that saying there is an
> important
> > man power requirement .
> >
> > Another disadvantage is that when a person wishes to make an improvement
> > she/he is not able to study existing works and if possible to join to
> such
> > groups . There remains a possibility , mostly , to start from scratch in
> > isolation.
>
> This stands for all projects...  Not everyone makes all of their work
> available, nor do they necessarily have it in a clean enough state that
> it is even usable...  For finding out about the project, post to one
> of the mailing lists, or look at the svn history to see who is recently
> most active and drop them an email...  Most projects require some
> reading of documentation available before you can meaningfully
> contribute to a project..
>
> > Many points are documented in FreeBSD wiki . In the svn , I did not see
> any
> > html file that presents links to such pages ( there may exist some but
> > seems that they are very rare ) .
>
> Did you read any of the handbooks on https://www.FreeBSD.org?  There is
> more information there than on the wiki...
>
> > I am sorry to be very negative , but I think there is no any other choice
> > to explain above ideas .
> >
> > For example , I am studying
> >
> > https://svnweb.freebsd.org/base/head/contrib/expat/
> >
> > In it , there is a directory
> >
> > https://svnweb.freebsd.org/base/head/contrib/expat/tests/
> >
> > it contains
> >
> >
> https://svnweb.freebsd.org/base/head/contrib/expat/tests/README.txt?view=markup
> >
> > but it does not contain any link to information how to use new kyua
> testing
> > facility for these tests .
> >
> > It may be said that "You should know !" , but my problem is "How ?" .
>
> By reading the documentation...  Though the use of kyua is very new,
> so I'm not sure how well the documentation is for that...
>
> > I do NOT expect that all of the directories can be populated with such
> > informative files immediately . In some very distant places , there may
> be
> > many informative pages , but how I can know where they are . It may be
> said
> > "Search " , but "What ?" .
>
> Read the various handbooks, like:
>
> https://www.freebsd.org/doc/en/books/developers-handbook/introduction-layout.html
>
> which is part of the Developers Handbook at:
> https://www.freebsd.org/doc/en/books/developers-handbook/index.html
>
> > My suggestion is to start such a convention with the goal that such
> > informative files will attract  more people to make contributions and
> also
> > will be a good documentation about FreeBSD maintenance .
>
> If you don't think the handbook describes enough, or any of the other
> documentation is enough at: https://www.freebsd.org/docs.html
>
> Please let us know exactly what can help...  The project has a lot of
> documentation, probably too much, but yes, some times it's hard to find..
>
> --
>   John-Mark Gurney                              Voice: +1 415 225 5579
>
>      "All that I will do, has been done, All that I have, has not."
>



(1)

Assume the other main directories are containing files such as

https://svnweb.freebsd.org/base/head/README?view=markup

with information about their contents .


(2)

Assume directory :

https://svnweb.freebsd.org/base/head/usr.sbin/pkg/



A small html file containing links to some related pages , such as :

https://github.com/freebsd/pkg
https://wiki.freebsd.org/pkgng
http://jenkins.mouf.net/job/pkg/



With such files , related information will be connected to each other and
traversing them will be very easy .





Thank you very much .

Mehmet Erol Sanliturk