From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: =?utf-8?B?7KGw7ISx67mI?= Newsgroups: gmane.emacs.devel Subject: Re: Review a blog post about emacs-devel Date: Fri, 1 May 2020 01:26:05 +0900 Message-ID: References: <2D56B465-C028-41AE-8D07-38C1C49FF5F7@gmail.com> Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\)) Content-Type: text/plain; charset=utf-8; delsp=yes; format=flowed Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="99574"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Yuan Fu , Emacs developers To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Apr 30 18:35:00 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jUC9L-000PfA-P2 for ged-emacs-devel@m.gmane-mx.org; Thu, 30 Apr 2020 18:34:59 +0200 Original-Received: from localhost ([::1]:44326 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUC9K-0001uN-OF for ged-emacs-devel@m.gmane-mx.org; Thu, 30 Apr 2020 12:34:58 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48848) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUC1B-0006l1-PU for emacs-devel@gnu.org; Thu, 30 Apr 2020 12:26:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jUC0t-0004l3-Tn for emacs-devel@gnu.org; Thu, 30 Apr 2020 12:26:33 -0400 Original-Received: from pv50p00im-ztdg10021801.me.com ([17.58.6.56]:38699) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUC0t-0004hi-9D for emacs-devel@gnu.org; Thu, 30 Apr 2020 12:26:15 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=icloud.com; s=1a1hai; t=1588263971; bh=s+6xde66XuztJ15jubJpquho9MM3U/MSf3+koJ/lRY8=; h=Content-Type:Subject:From:Date:Message-Id:To; b=grl2TaAz/NWvrUtZyPQegu9oanhnHxANa5mkmkQDN2pVHzHxZosdp1EPb1QXrLIfx DQaQ3el+D2Af+ahueZ8tqBcJqER2QmaP26M/jKn4ad11x4nmv8bClfxaD5v1NxlABZ hZUiHExgEfyEnxQHcRJtBvz98ppAXLKw6h0WSyNY6jAxlIwEVzqTJPsEQswTNoMQRh u5ikUKTUVUzvy/JelcbJSXIXz7KeA4MYJibBlyEWyO+j/tDYgYD89VxvGmlZMnK/EI 4J8FBZ/YQzfIom3hEHtYWHmEqQAQRLlN/Otocp0W0EG7+QgyT8iobadGRIDj0rd0sw ppEL9fLh7jJNA== Original-Received: from [192.168.0.2] (unknown [1.230.108.64]) by pv50p00im-ztdg10021801.me.com (Postfix) with ESMTPSA id 77DFC360364; Thu, 30 Apr 2020 16:26:09 +0000 (UTC) In-Reply-To: X-Mailer: Apple Mail (2.3608.80.23.2.2) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.138, 18.0.676 definitions=2020-04-30_11:2020-04-30, 2020-04-30 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-2002250000 definitions=main-2004300131 Received-SPF: pass client-ip=17.58.6.56; envelope-from=pcr910303@icloud.com; helo=pv50p00im-ztdg10021801.me.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/04/30 12:26:12 X-ACL-Warn: Detected OS = Linux 3.11 and newer X-Received-From: 17.58.6.56 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:248248 Archived-At: Richard Stallman 작성: > [[[ To any NSA and FBI agents reading my email: please consider ]]] > [[[ whether defending the US Constitution against all enemies, ]]] > [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > > Would you please talk about "free software" or "libre software", not > "open source"? > > The free software movement campaigns for software to respect users' > freedom. See https://gnu.org/philosophy/free-sw.html for the > explanation of the four essential freedoms. The ides of the free > software movement is that denying a user these four freedoms is an > injustice, and that we aim to end that injustice. See > https://gnu.org/philosophy/free-software-even-more-important.html. > > In 1998, people who disagreed with the free software movement's > philosophy coined the term "open source" with the aim of causing the > free software movement to be hidden behind a dense cloud of "open > source" so that people would forget about our ideas. Therefore, we > must give high proprity to showing people that we shand for free > software and _not_ for open source. We never use the words "open > source", or even "open" as an adjective applied to software, > except to explain that it is NOT what we stand for. From what I read… > The introduction of the term "open source software" was a deliberate > effort to make this field of endeavor more understandable to newcomers > and to business, which was viewed as necessary to its spread to a broader > community of users. The problem with the main earlier label, "free > software," was not its political connotations, but that—to newcomers—its > seeming focus on price is distracting. Is it not true? (That’s from Christine Peterson.) > See https://gnu.org/philosophy/open-source-misses-the-point.html > for more explanation. > > Also, please don't use GitHub as a standard of comparison. That would > promote GitHub, which is counter to what we aim to do. From what I understand is that the blog post isn’t a GNU one but a personal post? I don’t think it’s trying to speak for the GNU project. > Please don't promote Emacs Lisp packages that we don't have papers > to include in Emacs or GNU ELPA. That includes Magit. Same as above. > Jonas Bernoulli recently asked for access to the Emacs repo. That > suggests that we have made progress on the needed papers and be able > incorporate Magit into Emacs soon. Then we could document it here, > and in the Emacs manual. > > But we must not count that chicken until it hatches. Therefore, I > have commented out that text with #'s. The idea is that it should not > appear in the document we publish, but we should not lose it because > we will want to include it in the future. > > I do not know Org mode syntax, so I may have made errors in editing it. > > Here is my edited draft. > > > > #+SETUPFILE: ../../setup.org > #+TITLE: Contributing to Emacs > #+DATE: <2020-04-25 Sat 16:59> > #+TAGS: Emacs Hacker > #+OPTIONS: toc:1 > > Emacs, /the/ editor we all use and love, has been running for decades, > receiving contribution from hundreds of hackers along the way. But > because it predates “modern” libre software workflows by many years, you > can’t do the usual thing—open issues, fork and make PR’s, etc. However, > Emacs’s development workflow isn’t as tedious and difficult as many > people imagines (in particular, you don’t need Gnus or deal with email in > Emacs, or setup anything fancy). In this post I show what I’ve learned as > a Emacs new comer about participating the development of Emacs. I hope > that by sharing people what does contributing to Emacs look like, more > people knows what to expect and feels comfortable to join the development > of Emacs. > > * Report Emacs bug > > I won’t go into details here, because I think most people nowadays are > well educated by numerous libre projects on how to properly report a bug. > In the case of Emacs, in addition, you want to reproduce the bug with > vanilla Emacs, i.e., without your configurations. You can start one with > =emacs -Q=. And in Emacs type =M-x report-emacs-bug RET=, then =C-x M-i= > to use your mail application to send the bug report through email (Emacs > instructs you of all this). Then just wait for a developer to reply your > email (see? No setup needed). The only thing to remember is to make sure > you use “reply all” when replying emails (more on that in [[The mailing > list]].) > > * The mailing list > > We keep track of pending bug reports using the mailing list. A mailing > list has subscribers. When some one sends a mail to (or cc) the mailing > list address, the mailing list server forwards that message to every > subscribers, so every body sees your mail. To start a new thread, send a > mail to the mailing list server; to reply to someone’s message, simply > “reply all”. *Make sure you use “reply all” when replying to messages.* > If the message isn’t CC’ed to the mailing list server > (emacs-devel@gnu.org), other people on the list can’t see it. > > ** Subscribe to Emacs-devel mailing list > > Go to [[https://lists.gnu.org/mailman/listinfo/emacs-devel][Emacs-devel > Info Page]], and fill in the form to subscribe. Make sure you select “No” > for “Would you like to receive list mail batched in a daily digest?”. If > you select “Yes”, instead of receiving messages, you receive a “daily > digest” everyday, which is more or less useless becase 1) you don’t see > the full conversation, 2) you can’t participate the discussion. > > ** Tips > > Emacs-devel is busy, there are a couple dozen messages everyday, if you > don’t want your inbox flooded, you better setup a separate mail folder > for them. As an example, this is what I do on Gmail: I go to “Settings”, > “Filters and Blocked Addresses”, “Create a new filter”, filter any mail > that has the words “emacs-devel@gnu.org”, and asks Gmail to skip the > inbox and apply “emacs-devel” label. The effect is that all emacs-devel > messages don’t appear in your inbox and instead show up in emacs-devel > folder. > > ** No one replies? > > In general, give it a week or so before pinging your message. Normally > when no one reply to a new message, it is because people have seen it > don’t know enough to say anything intelligent about the topic. On the > other hand, don’t send a bug report without a patch to emacs-devel, > report it as a bug (even if you are not sure if it should be classified > as a bug, report it as a bug). > > * Get Emacs’ source > > - This is Emacs’ savannah homepage: > [[https://savannah.gnu.org/projects/emacs/]] > - This is Emacs’ git source page: > http://git.savannah.gnu.org/cgit/emacs.git > > The home page tells you how to clone Emacs’ source: > #+begin_src shell > git clone -b master git://git.sv.gnu.org/emacs.git > #+end_src > > Once you have the source, you can find most of the information mentioned > in this post in =/CONTRIBUTE=. For example, the first section clearly > demonstrates how to compile Emacs: > #+begin_src shell > # More info is in INSTALL. > ./autogen.sh > # You can use ./configure.sh --help to see the avaliable options. > # This is the step where you enable/disable optional functionalities > # like dynamic module, portable dumper, svg, etc. > ./configure.sh > make > #+end_src > > And the executable is =/src/emacs=, welcome to the future (release)! > # --enable-checking=yes --enable-check-lisp-object-type=yes > > * I have some code, what now? > ** The copyright assignment > > Every non-trivial contribution to GNU Emacs needs to have a copyright > assignment signed. Basically by signing the assignment, you give the > copyright of your code to FSF. See more at > [[https://www.gnu.org/licenses/why-assign.en.html][Why Copyright > Assignment]]. You need to first check with your employer before signing > it. Most of the time it’s no problem. To sign the assignment, ask for a > form on the mailing list, and someone will send you the form. You fill it > in and send to the instructed “FSF clerk”, then he sends you the document > to sign, either by email or by mail. You sign it and send it back, and he > sends you the final document with FSF signature. > > ** Conventions in code > > - Write regular sentences in comment, i.e., with capitalization and > period. Format comments with =M-q= (~fill-paragraph~). > - Comments should be in American English and with two spaces after every > sentence. > - Don’t make comment lines longer than 70 columns. > > ** Conventions in commit messages > > The general format: > # I added zero width space before each star to prevent Org from > considering them as headings > #+begin_example > Summary line (no ending period) > > Some more info (optional). > > ​* file: Change. > ​* file (variable1): Change. > ​* file (function1, function2, variable3): Same change. > ​* file (variable1): Change 1. > (function2): Change 2. > (function1, macro2): Same change. > #+end_example > > - The file path is relative to the source root, e.g., > =/lisp/progmodes/gdb-mi.el=. > - In =Change=, document /what/ changed, not /why/ the change is made. > /“Why”/ is better put in the comments. > - For new function​/​variable​/​macro, It suffice to say “New > function​/​variable​/​macro”. > - Don’t exceed 78 characters each line. > - Try to use only ASCII characters (so people on limited terminals can > view these messages). For example, prefer straight quotes over curly > quotes. > - Sames as comments—American English and two spaces after every sentence. > > ** Create patch and send it > > Create a single patch for each individual changes. Don’t send a patch > with three new features combined, that is harder to review; on the other > hand, don’t send a series of patches for a single feature, squash[fn:1] > them into one patch. Also, send your patch early and small and update > along the way, that also helps other people to review it. To save you > from googling, here’s some ways to create a patch: > > #1. Use magit. To generate a quick diff patch, create a diff buffer by > #either =d d= on a change or commit; in the diff buffer, hit =W s=. To > #generate a patch from a commit or a range of commits, go on to a > #commit and do =W c c=. This puts the patch file(s) under the project > #root and isn’t very convenient, I usually just do =! ! git > #format-patch -<# of commits> --stdout > .= > > 2. From command line, =git format-patch -<# of commits, e.g., 1> --stdout > > = > > To send your patch, write an email to the mailing list: > [[mailto:emacs-devel@gnu.org][emacs-devel]]. Drag your patch to the very > end of the message, after signatures. Normally this is all it needs. > Sometimes the message could be garbled; in that case, changing the > message to plain text usually helps. You can also send a patch to > debbugs, the bug tracker, if the patch is a bug fix. (See [[Debbugs]].) > > * NEWS and manual > > If you made a user-visible change, you should document this change in the > NEWS file, possibly also update the manual. *You don’t need to worry > about these until your patch is finalized, though. So maybe skip this > section for now.* And Emacs maintainers will let you know what to do. > Below is the relevant section in =/CONTRIBUTE=: > > #+begin_quote > Any change that matters to end-users should have an entry in etc/NEWS. > Try to start each NEWS entry with a sentence that summarizes the entry > and takes just one line -- this will allow to read NEWS in Outline > mode after hiding the body of each entry. > > Doc-strings should be updated together with the code. > > New defcustom's should always have a ':version' tag stating the first > Emacs version in which they will appear. Likewise with defcustom's > whose value is changed -- update their ':version' tag. > > Think about whether your change requires updating the manuals. If you > know it does not, mark the NEWS entry with "---". If you know > that *all* the necessary documentation updates have been made as part > of your changes or those by others, mark the entry with "+++". > Otherwise do not mark it. > > If your change requires updating the manuals to document new > functions/commands/variables/faces, then use the proper Texinfo > command to index them; for instance, use @vindex for variables and > @findex for functions/commands. For the full list of predefined indices, > see > https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html > or run the shell command 'info "(texinfo)Predefined Indices"'. > #+end_quote > > * Debbugs > > [[https://debbugs.gnu.org][Debbugs]] is the bug tracker for GNU operating > system. Here is [[https://debbugs.gnu.org/Emacs.html][Emacs’ debbugs home > page]]. I’ve covered how to report a bug. After you sent the email > reporting the bug, debbugs will reply to you a confirmation email with a > bug number. Instead of replying to messages in the bug report, you can > also comment by sending a message to =bug-number@gnu.debbugs.org=. When > the bug is fixed, you can send a message to > =-done@debbugs.gnu.org=, e.g., =40000-done@debbugs.gnu.org=. > That closes the bug. > > If you want to view currently pending bugs, you can either > [[https://debbugs.gnu.org/cgi/pkgreport.cgi?package=emacs;max-bugs=100;base-order=1;bug-rev=1][browse > online]], or view them in Emacs: install the package =debbugs= and =M-x > debbugs-gnu=. You can click on bugs to view them, and view the > conversation. You can even reply by =S w= on a message, and write your > message in Emacs, and hit =C-c C-c= to send. Chose “mail client” and > Emacs invokes your default mail application to send this mail. Hit =C-c > C-k= to cancel the message. > > * GNU ELPA > > Have a good package? Add it to GNU ELPA! Pros: > - Get reviews from people that knows Emacs and Emacs Lisp best. > - Instantly avaliable from vanilla Emacs. > - You /can/ host your package on other places. > Please see https://www.gnu.org/software/repo-criteria-evaluation.html > for our comments on some used repo sites. > - You /can/ push to your package without review, and don’t need to follow > Emacs conventions for commit messages. > - You need to sign the copyright assignment. And make sure all the > contributors of your package (with significant contribution, i.e., ~15 > lines) signs it. > > View > [[http://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/README][README]] > for more detailed info. > > [fn:1] Squash means combining several commits into one. It is easy to do > with Magit: =l l= go to the log buffer; then go to the earliest commit > you want to change, hit =r i=; hit =s= on the commits you wan to squash, > commits marked with “s” will squash up. You can also use =M-n/p= to move > the order of commits; then hit =C-c C-c= to edit the new commit message, > and =C-c C-c= again to confirm. > > > > -- > Dr Richard Stallman > Chief GNUisance of the GNU Project (https://gnu.org) > Founder, Free Software Foundation (https://fsf.org) > Internet Hall-of-Famer (https://internethalloffame.org)