From owner-freebsd-arch@FreeBSD.ORG Mon Nov 10 08:57:01 2014 Return-Path: Delivered-To: freebsd-arch@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 9D64BA8D for ; Mon, 10 Nov 2014 08:57:01 +0000 (UTC) Received: from mail-yk0-x233.google.com (mail-yk0-x233.google.com [IPv6:2607:f8b0:4002:c07::233]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority G2" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 55D7D1CD for ; Mon, 10 Nov 2014 08:57:01 +0000 (UTC) Received: by mail-yk0-f179.google.com with SMTP id 131so3966493ykp.10 for ; Mon, 10 Nov 2014 00:57:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=D78xe30yoNquvy/lk3yDEQsqKjZYP9PqpTIugS6KdEs=; b=Z64R/CgUkeGAhQkSe7mAzUhMG/3F2BdihcrH4Aam/RAdQegoKRltmKl50a3mDZLLFw WsVBOOGAlfYt5qc8+7wJfWsGqxK4FyhULZRJKW88nl0q506DAthZbqy2IImlKQJvanX5 +v1xVU9dgPeUUGqdMZbX5yFKbmD4nrWkXHlRN2/+CNqniLyfAfAIb7lk/GdEKxhNHfpi hJrAmWwttaSIYkcpQ6kq+XAMQcWV8nddYWu1g7VebNhVW5m6u7j4/qFuqu0EYg+lc9aH WstTc/8BGfgMsWpknUfcelTZaT2/z1+2w2L65g9trf+CF8+10Ua1f9gW6U+D20h8Zs33 m6zg== MIME-Version: 1.0 X-Received: by 10.170.196.72 with SMTP id n69mr31939739yke.41.1415609820457; Mon, 10 Nov 2014 00:57:00 -0800 (PST) Received: by 10.170.84.133 with HTTP; Mon, 10 Nov 2014 00:57:00 -0800 (PST) In-Reply-To: <20141110043244.GN24601@funkthat.com> References: <20141110043244.GN24601@funkthat.com> Date: Mon, 10 Nov 2014 00:57:00 -0800 Message-ID: Subject: Re: Lack of informative files in FreeBSD svn From: Mehmet Erol Sanliturk To: Mehmet Erol Sanliturk , FreeBSD Arch Content-Type: text/plain; charset=UTF-8 X-Content-Filtered-By: Mailman/MimeDel 2.1.18-1 X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 10 Nov 2014 08:57:01 -0000 On Sun, Nov 9, 2014 at 8:32 PM, John-Mark Gurney 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