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