Date: Mon, 10 Nov 2014 00:57:00 -0800 From: Mehmet Erol Sanliturk <m.e.sanliturk@gmail.com> To: Mehmet Erol Sanliturk <m.e.sanliturk@gmail.com>, FreeBSD Arch <freebsd-arch@freebsd.org> Subject: Re: Lack of informative files in FreeBSD svn Message-ID: <CAOgwaMvqbFbVZwBVLzM5oi7rOG1s5=AjE6ydXHH=iRz=B7QN_A@mail.gmail.com> In-Reply-To: <20141110043244.GN24601@funkthat.com> References: <CAOgwaMvi9jnd-kJDwoSAqrfL4mSEE77gaErrC-nCc45M2gJbAQ@mail.gmail.com> <20141110043244.GN24601@funkthat.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Nov 9, 2014 at 8:32 PM, John-Mark Gurney <jmg@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAOgwaMvqbFbVZwBVLzM5oi7rOG1s5=AjE6ydXHH=iRz=B7QN_A>