From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Leake Newsgroups: gmane.emacs.devel Subject: Re: More metaproblem Date: Sat, 06 Dec 2014 04:19:03 -0600 Message-ID: <85k325jd2g.fsf@stephe-leake.org> References: <20141203142859.24393.98673@vcs.savannah.gnu.org> <20141203192721.GE12748@thyrsus.com> <547F6774.50700@cs.ucla.edu> <838uio5vjw.fsf@gnu.org> <20141203211447.GB15111@thyrsus.com> <871toge5zw.fsf@floss.red-bean.com> <83388v6hsq.fsf@gnu.org> <87egsftgd5.fsf@ktab.red-bean.com> <85ppbymn91.fsf@stephe-leake.org> <87mw7257b8.fsf@ktab.red-bean.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1417861182 14030 80.91.229.3 (6 Dec 2014 10:19:42 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 6 Dec 2014 10:19:42 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 06 11:19:31 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XxCSY-0006EQ-Tu for ged-emacs-devel@m.gmane.org; Sat, 06 Dec 2014 11:19:31 +0100 Original-Received: from localhost ([::1]:53953 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxCSY-0003sk-FZ for ged-emacs-devel@m.gmane.org; Sat, 06 Dec 2014 05:19:30 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37595) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxCSG-0003sc-1N for emacs-devel@gnu.org; Sat, 06 Dec 2014 05:19:18 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XxCS9-00066Q-Q8 for emacs-devel@gnu.org; Sat, 06 Dec 2014 05:19:11 -0500 Original-Received: from dnvrco-outbound-snat.email.rr.com ([107.14.73.227]:65236 helo=dnvrco-oedge-vip.email.rr.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxCS9-000665-Ih for emacs-devel@gnu.org; Sat, 06 Dec 2014 05:19:05 -0500 Original-Received: from [70.94.38.149] ([70.94.38.149:52517] helo=TAKVER) by dnvrco-oedge02 (envelope-from ) (ecelerity 3.5.0.35861 r(Momo-dev:tip)) with ESMTP id 6B/4C-16151-818D2845; Sat, 06 Dec 2014 10:19:05 +0000 In-Reply-To: <87mw7257b8.fsf@ktab.red-bean.com> (Karl Fogel's message of "Fri, 05 Dec 2014 11:34:51 -0600") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.94 (windows-nt) X-RR-Connecting-IP: 107.14.64.130:25 X-Authority-Analysis: v=2.1 cv=bePlUY/B c=1 sm=1 tr=0 a=AppmJ/7ZOOFWL/q6u6u93g==:117 a=AppmJ/7ZOOFWL/q6u6u93g==:17 a=ayC55rCoAAAA:8 a=fNEgcOh0sVsA:10 a=9i_RQKNPAAAA:8 a=o2eD-HNaAAAA:8 a=7uWv3FMQu_5VhpoZVX0A:9 X-Cloudmark-Score: 0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 107.14.73.227 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:179132 Archived-At: Karl Fogel writes: > There needs to be place where a developer *who has not yet decided to > contribute to Emacs* can land and quickly get an impression of how much > work is involved, and what the nature of that work is. The _first_ thing I do when considering a project is to download the source code, and browse thru it. That tells me a lot about the culture, and whether I could stand to edit the code. The only things I get from project web pages are a sense of how many developers there are, how involved they are, how long the project has been around, what language and what CM system are used. The mailing list archive and bug tracker are good sources of information on the first few items. Other information on a typical project web page is aimed at people who might _use_ the project (ie a user guide/manual), as opposed to contribute to it. > If that impression is only available from a place like etc/CONTRIBUTE, > then we're effectively asking people to have made that decision before > they've gotten the information they need to be able to make it. Having just edited CONTRIBUTE, I must disagree. The sort of details that are in CONTRIBUTE are things that I would only worry about _after_ I had decided to work on a project, based on the above browse thru the code. There is a brief list "things you can work on other than code"; it's pretty standard, but it would make sense to have that on a prominent web page. CONTRIBUTE mostly talks about Changelog formats and how to use git; minor details (but frustrating when you don't know them). I was put off by bzr; but the information about which CM system Emacs uses is on the main Savannah web page, so there's no need to consult CONTRIBUTE for that. > It can be maintained in the Emacs tree, but it needs to be published in > a Web-standard way outside that tree (i.e., browsing to it in the > web-based git repository browser would be a poor user experience). A direct link to CONTRIBUTE in the web-based repository browser would be a good thing for the Savanah web page. Since CONTRIBUTE now references the wiki, along with several other sources of information, it might make sense that it be starting point. Hmm. It would be nice if the web links in CONTRIBUTE were presented by a non-Emacs browser as clickable links in that case. Currently, you have to copy and paste to the address bar. Of course, if you browse the web in Emacs, or just read the text file in Emacs, they _are_ clickable! So perhpas the first line of CONTRIBUTE should be "This file is best read in Emacs" :). But it's probably best to keep the wiki as the primary reference from the Savannah web page, and have it explain about CONTRIBUTE. I'll work on the wiki next, but it's much more of a mess than admin/notes/* Which is a big reason I prefer files in the repository over a wiki; the repository is kept much cleaner, because people review it. >>Emacs was around long before "web pages". It has been slow to embrace >>web pages, because it already has a culture that works well without >>them. >> >>Perhaps that needs to change to attract new blood, but I'm not sure. >>Emacs has a _very_ different feel than "typical" development >>environments; using a unique development environment for creating Emacs >>can ensure that is maintained. > > Even people who use Emacs for almost everything rarely use it as their > primary web browser. A few do, but most don't. As I think across all > the Emacs-first developers I know -- people like me who use Emacs as > their shell, as their mailreader, as their primary development > environment, as their primary text composition, and as their organizer > via Org Mode -- they still use a dedicated browser like Firefox for > browsing the web. True (I use Emacs as you do). But I don't see how that addresses the question of where the information in CONTRIBUTE should reside. > So for information that people typically expect to be on the Web, such > as developer guidelines for contributing to a free software project, > we'll be better off putting that on the Web. Every free software project I've worked on has the "how to use our CM system" info in a file in the CM repository, not on the web. (that includes monotone, emacs, opentoken, dvc). So apparently we have very different experiences, or we are talking about different information. > Because the people who need to read it the most, the people who are > the most important to us -- proficient Emacs users who are > *considering* becoming contributors but who have not decided yet -- > will expect to find it on the Web anyway, and will most likely first > read it in an environment other than Emacs. People who write elisp for Emacs must be used to reading the elisp source. That doesn't mean they have the repository checked out; the "binary" install includes the elisp source, but not the full source tree. Many people who use Emacs compile it from the release tarball, to get the latest release. For others, it's a pretty small step to either unpack the release tarball or checkout the git repository. So I don't see a significant barrier here. > One solution would be to write those docs in (say) Markdown and > autogenerate the HTML pages, so that reading them and editing them in > Emacs is easy, but we still get HTML for the web site. I would not mind doing that (that's how it works in monotone), but I don't see how that addresses the original problem, which was that several people who were contributing were unaware of the documentation on the processes. And it definitely takes resources to support; the machinery that does this in monotone breaks occasionally. -- -- Stephe