# -*- mode: org -*- Archived entries from file /home/kfogel/src/producingoss/todo.org * DONE Build system fixes (re thread with Wolf): :PROPERTIES: :ARCHIVE_TIME: 2013-04-24 Wed 08:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: 1) Make build system work smoothly on live site. 2) Make it show syntax errors when there are any, so translators can diagnose and fix without having to have Docbook Lite running locally. * DONE (r2898) Forced proprietary relicensing for mobile app stores. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 15:43 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: From: Nathan Toone Subject: [KNOTSPAM] Suggestion for book To: Karl Fogel Date: Sat, 27 Jun 2015 12:17:33 -0600 I have been reading the updates to your book - and have a suggestion, particularly for the page in chapter 10 about Proprietary Relicensing Schemes: http://producingoss.com/en/proprietary-relicensing.html In this section, you come down pretty hard (and rightly so - I can see your arguments) *AGAINST* doing proprietary relicensing - but there are some licenses (GPL in particular - and I would guess most copyleft licenses in general) whose terms make them unable to be distributed in mobile app stores (Apple/Android/etc.). It might be worth a section there to discuss the issues surround that - and what suggestions you may have in that situation. Your arguments against doing dual licensing are completely valid, but personally, I have worked on a project that wanted to be GPL-licensed, and we ended up having to do a dual-license scheme and collect CLAs for the specific purpose of being able to distribute the application on app stores. Some links that we used to help us navigate this issue were: http://www.engadget.com/2011/01/09/the-gpl-the-app-store-and-you/ https://bonsansnom.wordpress.com/2011/01/08/ about-apple-store-gpls-vlc-and-betrains/ No specific or personal response to me is needed…I just thought I’d make a suggestion that might be helpful in the update for your (wonderful, amazing, helpful, invaluable, superb, ) book! I may hop on IRC some time this week and try and ping you - in case this email doesn’t come through…or feel free to reach me by email or #toonetown on freenode. -Nathan * Mention Gabriella Coleman's book in preface or appendix or somewhere. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 16:17 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * In Chapter 7, update for JavaScript projects and other :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:06 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: continuous development / auto-deployment situations. Also, commit IDs as release numbers, in certain circumstances. * Ask Ben Reser and Hyrum Wright if they'll review Chapter 7? :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:19 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Ask Ben Reser to review "Announcing Security Vulnerabilities" :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:19 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: in Chapter 6, to make sure I'm not missing anything important. * DONE (r2903) Tell readers that SaaS-on-open-source-software is a thing. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:36 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: In Jenn Brandel's words: "Wanted to remind you (before I forget!) for you to note the software / service difference re: the dual licensing section of your book. Just to make the distinction that there's no problem in charging for a service built on open source code." See also: http://nucivic.com/opensaas-future-government-innovation/ * DONE (r2903) Minor consistency fixes (easy): :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:44 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: - "codebase" not "code base" - in todo notes, use "poss2" not "possv2" * DONE (r2903) Mention other OSS forge platforms, alongside Gitorious, etc. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:50 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: - http://kallithea-scm.org/ (no hosting sites as of [2016-01-30], so not listing it in this edition. Hopefully next edition!) - Phabricator.org. Michael Akinde says to look at this blog post: http://blogs.gnome.org/aklapper/2014/05/19/wikimedia-phabricator/ * http://cia.vc no longer exists :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:56 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :END: * Google Code Hosting now supports git :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:56 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :END: * DONE (r2903) Linux release numbering has since changed :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:57 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :ARCHIVE_TODO: DONE :END: * typo "Public list mailing list"? :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:57 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :END: * MySQL history needs to be updated as the fork already happened. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:58 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :END: * In the eBook (read the ePUB I converted to MOBI) the Fossil :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:58 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Bugs reported by Gerhard Poul :ARCHIVE_CATEGORY: poss :END: section refers to itself instead of veracity; this doesn't seem to be a problem in the HTML version that is currently on the web, though, so may also be a conversion issue. * Bugs reported by Gerhard Poul :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 17:59 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: ** http://cia.vc no longer exists ** Google Code Hosting now supports git ** DONE (r2903) Linux release numbering has since changed ** typo "Public list mailing list"? ** MySQL history needs to be updated as the fork already happened. ** In the eBook (read the ePUB I converted to MOBI) the Fossil section refers to itself instead of veracity; this doesn't seem to be a problem in the HTML version that is currently on the web, though, so may also be a conversion issue. * Search for everywhere "freecode" is mentioned, see if still right. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:02 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Check for "opensource.org/licenses/*", fix to use SPDX URLs. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:02 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Make sure the book recommends copyright ownership for new code. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:02 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: Check if this is covered in legal chapter or elsewhere. * Dreamwidth :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:03 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Comb Jono Bacon's book again for topic coverage. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:03 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Check with Mike on status of EPL-2.0, re "license-choosing" in Ch. 10. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:05 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * GitHub, bug trackers update :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:05 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * See Mel Chua's mails :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:05 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * From Wolf :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:06 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: Date: Tue, 02 Oct 2012 17:23:34 +0200 Hi Karl, here you predict it, now it's become true ;-) > (no Git, at least not yet) http://producingoss.com/en/web-site.html#canned-hosting-choosing ...but I think this should be updated. ** note that web-based presentation of diffs on Google Code is thought ugly by some; compare to SF or GitHub. GitHub has commenting on commits (line-based if nessesary!), though, and it's fast too. * Check out Simon's columns, of course. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * "Open source policy no guarantee governments will actually use open source" from FierceGovIT :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Mark Atwood re Open Stack :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Android as a model. (See also TDF call notes.) :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * Cornelius Schumacher volunteered to discuss KDE. :PROPERTIES: :ARCHIVE_TIME: 2016-01-30 Sat 18:09 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: poss :END: * DONE Formatting sanity check: :PROPERTIES: :ARCHIVE_TIME: 2016-02-06 Sat 17:01 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Everywhere the ' in ...' trick is used, make sure there is appropriate spacing around the "in". * DONE (r2825) Importance of real-life events (conferences, code sprints, hackathons, etc) :PROPERTIES: :ARCHIVE_TIME: 2016-02-06 Sat 17:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: From http://keimform.de/2007/freie-software-produzieren/ (translated): What is also missing, the importance of real-life events, ie conferences, code sprints, Doc sprints, work camps, etc. From my perspective and experience are such meetings for the social process in an active community is very important. * DONE Dustin Mitchell's comments: :PROPERTIES: :ARCHIVE_TIME: 2016-02-06 Sat 17:15 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: https://plus.google.com/u/0/105883044168332773236/posts/GPEj7Rm4C3w (must be signed in w/ personal gmail address to see it) The relevant, and presumably non-confidential, part of his comment: "The first edition addresses topics generally, with specifics geared toward the kinds of projects Karl was familiar with. That leaves other types of projects -- weekend hacks, single-author projects with a non-technical userbase, or corporate-sponsorted projects, for example -- reading between the lines for advice." To the extent I can address this, it is addressed now in the 2nd edition. * DONE Noel Hidalgo suggests camps, cons, hackathons, and kickstarting: :PROPERTIES: :ARCHIVE_TIME: 2016-02-06 Sat 17:17 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: I'd love to see a section in "kick starting" FOSS software & how social media plays an impact within these communities. Additionally, camps, cons, & hackathons should have their own chapter. Knowing how physical engagement plays into online engagement is critical. Re kickstarting: interview Joey Hess? Who else? * DONE The problem isn't money, it's monopoly. :PROPERTIES: :ARCHIVE_TIME: 2016-02-06 Sat 17:31 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Add a section about the distinction between commercial use and proprietary use. See email of [2014-10-06] with Subject line "License question" and MID <87oatpdwbb.fsf@ktab.red-bean.com>. * DONE "Bus Factor" :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 17:03 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: (suggested by Philip Olson , later a KS pledger) This is done now, see r2665. However, Philip is thanked in r2842. Some cross-linking should be done. * DONE (r2823, r2825) "Community editions" vs "commercial edition" terminology rant. :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 17:06 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Was a star note at the top of Chapter 10 (Legal). But is that chapter the right place for that? ch05.xml:"Enterprise Edition"). Aside from the fact that everyone knows there * DONE (r2914) SFLC copyright management guide: :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 17:12 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: http://softwarefreedom.org/resources/2012/ManagingCopyrightInformation.html * DONE (r2915) Improvements to sections about security procedures :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 17:43 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: ** breser points out don't use email to submit security bugs Pushing the ASF to stop using email to submit security issues. https://secsubmit.apache.org/ * kfogel looks ^ That doesn't go anywhere yet so don't use it. I didn't build that Humbedoh did but in response to my suggestion at Apache Con That reminds me that I need to update that section of my book, to say the same thing. Email is obviously the wrong way to transmit this kind of information. Ohh it's a fine way if both sides know how to deal with PGP. The problem is most don't. And in the case of an open source project they have to encrypt to multiple people. That is partly out of my annoyance at the ASF security team's behavior of taking encrypted mail, decrypting it and then posting it to the security/private list for a project. yeah -- I really think PGP/GPG is great but only in certain limited use cases I mean, unless everyone's going to set up Schleuder, but even then it's not a perfect win Feel free to weigh in here: http://mail-archives.apache.org/mod_mbox/www-infrastructure-dev/201404.mbox/%3C5357F5D6.1020209%40cord.dk%3E Nah, I don't think I'm likely to have a uniquely valuable opinion that's not already being better represented by someone taking more active part in the discussion Do you mind if I record a snapshot of this part of our conversation in a book-notes file that's publicly visible (to those who know where to look)? I also have a private notes file I can use, if not. Go right ahead, nothing sensitive here. ** jorendorff's question about read access to security bugs, apparently an internal debate at Mozilla citing http://blog.gerv.net/2011/12/a-level-playing-field/ which cites POSS story about Mike Pilato and commit access. See IRC transcript in #red-bean of 2012-08-15. * DONE (r2660) From Wolf Peuker :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 17:57 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Date: Tue, 02 Oct 2012 10:58:11 +0200 First, I was working on the IRC section, there was a list of open source pastebin sites (gray box): http://producingoss.com/en/irc.html What do you think on Gist https://gist.github.com/ as run by GitHub? Is it popular? Should it be in the list? Second, I translated RSS section into German. There were some readers mentioned. I think modern mail clients or browsers can be used to. I don't know if it's really popular, but I read RSS only within Thunderbird, my mail client. Should this be made explicit? * David Eaves's "Science of Community Management" :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 18:25 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :END: http://eaves.ca/2012/11/15/making-bug-fixing-more-efficient-and-pleasant-this-made-me-smile/ http://www.youtube.com/watch?v=TvteDoRSRr8 * Matt Doar suggests stackoverflow-type forums, shared spreadsheets, etc. :PROPERTIES: :ARCHIVE_TIME: 2016-02-07 Sun 18:25 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :END: I'd like to see forums and stackoverflow-like sites referred to as well as mailing lists For bug trackers, a paragraph on why email and shared spreadsheets such as Google Docs don't usually work well enough for this purpose. Fields such as as priority and severity should always be clearly described or arguments break out when their values get changed * Inner-sourcing, "community source", and other half-source things :PROPERTIES: :ARCHIVE_TIME: 2016-03-19 Sat 20:35 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :END: Inner sourcing isn't really like open source: the actors are ultimately all part of the same hierarchical authority structure, so true permissionless initiative is hard to achieve, and it also fails the "portable résumé" test -- you can't take the code with you, so you can still be alienated from your work, so some of the motivation to invest personally is gone. * DONE How to handle the worry about offering infinite support :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 15:15 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: (Already covered in "Dispel Myths Within Your Organization".) Many orgs (esp non-profits and gov't customers and their contractors) worry about the degree to which they might be required to engage & meet expectations of third parties, e.g., in responding to questions in public forums, in meeting roadmap deadlines, feature goals, etc. This is especially true when the project is open source from the start. Answer is to clearly define & agree on what obligations are: paying customers come first, and then make a conscious choice about controlling the other costs. Explicitly follow up in public forums to say "We're heads-down working on features right now [or whatever], but there was this thread from so-and-so a few months ago that might have an answer. [link] So-and-so, do you have anything to add?" over to community experts. "You open source your code, not your time and attention." (But see reference in notes.org to Koen van Daele's email "Re: Arches" in Aug/Sep 2012, for an argument the other way.) * In Ch. 3, "Bug Tracker", maybe talk about how the bug tracker is :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 16:11 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :END: as important to watch as the repository? * "Ask Slashdot: Where Do You Get (or Share) News About Open Source Projects?" :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 16:29 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :END: http://developers.slashdot.org/story/14/07/26/2238223/ask-slashdot-where-do-you-get-or-share-news-about-open-source-projects?utm_source=rss1.0mainlinkanon&utm_medium=feed Answer: Latest site is http://freshcode.club/, and it looks good, but times have changed since freshmeat and freecode. Although I might use the site as a reference or news source now, it's not really that important that people try to get their new releases posted -- rather, it's important to freshcode.club but not to the projects. So there's no reason to mention it in the book. * DONE CDT spam report dead link bug filed (for link in Chapter 3). :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 16:37 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas/Do a general link check. :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Latest update: they're supposed to let me know whether the link can now be relied on (see thread in "cdt" mail folder). Filed this via https://www.cdt.org/contact on [2013-12-18]: Hi. The page https://www.cdt.org/pr_statement/cdt-releases-new-report-origins-spam links to three pages under "Supporting Documents", all of which get "Page Not Found" errors: http://cdt.org/speech/spam/ http://cdt.org/speech/spam/030319spamreport.shtml http://cdt.org/speech/spam/030319spamreport.pdf Can that spam report be restored to the CDT web site and the links fixed? Thank you, -Karl Fogel * DONE Do a general link check. :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 18:30 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: ** DONE Check where http:// URLs can be https://, use the latter where possible. * DONE In Chapter 3 "Mailing List / Message Forum Software", list Discourse. :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 18:44 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: * DONE In Ch. 6, many examples use rev IDs rather than commit IDs. :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 18:59 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: The principle is the same either way, but will readers be thrown by the syntax? Would be good to at least point out that "commit FOO" means the same thing, and that the details of the syntax are not as important as *having* a syntax. * DONE In Ch. 6, many examples use rev IDs rather than commit IDs. :PROPERTIES: :ARCHIVE_TIME: 2016-03-20 Sun 18:59 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Content ideas :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: The principle is the same either way, but will readers be thrown by the syntax? Would be good to at least point out that "commit FOO" means the same thing, and that the details of the syntax are not as important as *having* a syntax. * Chapter 1 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-05 Thu 18:40 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: By the way, for both the preface and some marketing material, we need to list the main changes to the new edition. I guess the opening ("Most free software projects fail.") seemed like a powerful statement when we put out the first edition, but this time I worry a bit about starting out with negatives. What about the stoned-soup miracle of seeing value created out of many small contributions by many strangers? What about the joys of community (as one finds, for instance, at DebConf)? What about the uncorruptible and unbreakable persistence of a project that meet people's needs? I would start with a page about those and then move to failure. Right at the beginning: "We tend not to hear very much about the failures..." This paragraph seems longer than necessary. You make a good point, but make it in two sentences and move on. List of myths and causes of failure, pages 1-2: Consider adding a bit of structure, perhaps through a variablelist: open source as panacea, lack of packaging, lack of active management, etc. Page 3: "some adjustments will usually be needed." Who has to adjust? The risk-averse organization, or the open source developers? Page 6: about BSD. Although that projects produced a lot of critical code still in widespread use, and OSes that powered a lot of projects, the organizations producing the various OSes diverged from what we now see as good free software practices, and the projects suffered. (The fragmentation and forks were symptoms of that.) I don't think you need to go into all that in Chapter 1, but it might be a useful topic for later chapters. If you don't mind getting the flames. X Windows: I'd rather not use a sloppy term, particularly because MS trademarked Windows. You could just give the full name once and then call it X. Page 7: "of course it always cost less." This could trigger complaints about the complicated TCO problem. It might be more accurate to say "of course, people with some computing skill could always use it reduce their software costs." A big addition to your Chapter 1 history: the renewed popularity of SaaS in the 1990s (it has existed in some form for decades, of course) presents a new challenge that the FSF responded to quickly and that your chapter needs to cover. It can take up just a few paragraphs, but there are a lot of subtleties. The counter-intuitive fact is that free software has flourished more and more as SaaS grows. I would like to see people adopt the term "closed core" to describe the phenomenon. I introduced that term in 2011: http://radar.oreilly.com/2011/12/could-closed-core-prove-a-more.html You already described the phenomenon earlier, to explain why companies invest in open source, but this is a bit of an extra twist. * Chapter 2 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-06 Fri 17:42 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Pages 11-12: Some of this material perhaps should not be right at the beginning of the chapter. Basically, how to present yourself to the outside world is a secondary or tertiary topic. The chapter contains other, more basic issues such as whether to create a new project in the first place. [I modified the intro quite a bit, but kept the ordering. I think presentation is important enough to come first. -Karl] Pages 11-12, concerning the look of the web site: It might be worth mentioning that sophisticated projects usually include an introductory video. Many developers haven't gotten used to the video culture yet (I imagine that young ones have, though), and it's worth highlighting the availability of some kind of video presentation because it takes a lot of work but seems to have a big payoff. (Of course, the topic is also appropriate for Chapter 6, Communications.) [Looks like I did this in r2585, back in 2013. I'm comfortable with where it's discussed, later in this chapter. -Karl] Starting From What You Have, Pages 12-13: you introduce a number of requirements here quite quickly: a mission statement, a well-organized code tree, etc. Some of these are explained later, which is fine. But the presentation here is a welter of partially related concepts. I tend to like tidiness, so I go for variable lists laying out each requirement precisely (you can still follow up later with more information). Even if you don't use a variable list, think carefully about what you're asking the reader to do and be clear what the requirements are. You may well discover that some requirement--for instance, code tree--needs more explanation later in the chapter. [Considered it, but I like the way it flows now, and worry that it would look too much like a technical manual if I switched it to a variable list. This kind of "variable list disguised as a long prose passage broken up with headings" was actually my desired effect; I realize it might not be to everyone's taste, of course. -Karl] Choose a Good Name: no changes to suggest, but I have an interesting story to tell. I visited the George Eastman home in Rochester and heard how he created the name Kodak. Already in 1888 he was thinking globally, and he wanted a simple word whose pronunciation would be obvious to anyone who was familiar with Roman letters. The name had no other meaning. [I'd heard that story, yeah! Clever. Would have been more clever if they'd noticed the digital camera revolution in time, but can't have everything I guess :-). Cough cough. -Karl] Alpha and Beta, page 17: I believe that Alpha releases are usually free to evolve and change the APIs and functionality, where Beta releases aren't supposed to so except in cases of dire necessity. That is also worth mentioning. [Very good point. Fixed. -Karl] Communications Channels (page 19): I would say a little here about choosing good terms that aid in SEO. Be aware of what people search for, what similar projects use, what terms are used by projects you want to interface with, etc. [Is this related to Communications Channels? I wasn't sure how to fit it in here. Also, although it is good advice, it's not really specific to open source projects, and people hopefully should be able to figure this out on their own. If they don't know that basic principle of web communication, I'm not sure this book can help them. -Karl] Developer Guidelines, page 20; I would mention codes of conduct in this section, because you don't get to them until page 29. [Done. -K] Documentation, page 21: Nowadays, much documentation is stored as a wiki to make it easy for contributors to change it. This might be worth mentioning. (You mention a wiki under "Hosting" later.) Some sites don't want to make the documentation too open to change, but sometimes it's a good way to get users involved. [Seems to be already handled. -K] "If users interact with your code primarily over a network": sidebar, page 25: Almost any software is liable to be used by people over a network, I think. Whatever is useful to users is likely to be incorporated by someone into a SaaS service for those users. Think of a compiler or interpretor, for instance. Doesn't look like web software, but don't sites offer text boxes where you can paste in and run code? [I've clarified the text there. -K] Code of Conduct: "It is always up to the project leadership, by which I mean those whom others in the project tend to listen to the most, to see to it that a code of conduct is used wisely." (page 30) It's also up to leadership to enforce the code, taking action as soon as a violation is noticed. [Adjusted text accordingly. -K] Practice Conspicuous Code Review and Case study (pages 30-31): should these be in the Getting Started chapter? I think they could wait till a later chapter. Perhaps it could go in Chapter 4, Social and Political Infrastructure. If it's a different level of activity from Chapter 4, it could probably fit somewhere in Chapter 5, perhaps as a sub-section of Open Source and the Organization. [It's certainly a judgement call, but I think it belongs here in "Setting the Tone" because that's one of its most important effects (separate from improving the quality of the code). -K] Be Open From Day One (pages 32-33) and Opening a Formerly Closed Project (pages 33-34: I would reorganize these a little. You give three problems in these sections with closed projects that go open: 1) there are hidden proprietary elements to be stripped out; 2) opening the code creates a big unnecessary event, 3) there are cultural and managerial practices that make it hard for developers and the company as a whole to convert. I'd describe those things as subsections of "Be Open From Day One." Then the section "Opening a Formerly Closed Project" can be shortened and can focus on anticipating and fixing the cultural problems. [I think I may have done this already? At any rate, the problems described above don't seem to me to be present anymore, and the latter section does now link back to the former in the ways I would expect. -Karl] Announcing (pages 35-36): Here, again, I'd remind the reader to choose SEO-appropriate terms that will cause searches to work well. [Okay, despite my earlier aversion to discussing SEO explicitly, I've put a note about it here, as well as updating some out-of-date material about generic announcement sites. -K] * Chapter 9 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-06 Fri 21:16 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: AGPL (pages 195-196): I believe the idea for this license historically arose as discussions were just beginning for the GPL 3, and some participants (perhaps even including RMS) wanted the GPL 3 to include the critical clause. Pushback from others who were less hostile to cloud services (which didn't even have that name then) led to a split between the GPL 3 and the AGPL. I am not sure of this, but it's my recollection. I don't know whether it's worth mentioning. [I think the history is interesting personally, but not relevant enough to readers to include. -K] * Chapter 8 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-06 Fri 22:05 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Politics (page 162): a valuable enough point to be a section or sidebar. [Thanks. I considered it, but generally I prefer to use sidebars for definitions or for discrete thoughts that are, at least in theory, separable from the main body of text around them. The point about politics made here seems to me to be connected enough to the rest of the section that I'd like to keep it part of the section. -Karl] Automated testing (pages 168-170): Is it worth mentioning test-driven development, just as a process used by many projects? [I'm inclined not to. There are too many methodologies to mention each one, and I'm not convinced that TDD is more relevant to open source than it is to any other kind of software project. I did update this section to discuss unit testing as well as regression testing, though. -K] Meeting in Person (page 172): I'm glad you keep this short, instead of entering deeply into a big topic. It may be worth referring to Jono's book The Art of Community for detail, because he has the subject nicely covered. One topic you might want to devote a couple sentences to, though, is the cost of attending. The project may want to sponsor certain people and perhaps run votes or use some other system to determine who gets a scholarship. [I thought about it, and reviewed what Jono says there. It's good material, but I think it doesn't connect well with what's here. The cost issue will present itself fairly clearly to anyone who's actually budgeting for one of these, so I don't think I need to spend space on it here. If I discuss the benefits, then the reader can weigh those against the costs -- they don't need me to tell them that there are costs :-). -Karl] Documentation manager (pages 175-176): you have come to my favorite topic, of course. We can't teach people here how to write readable and actionable documentation. But there is one thing I would like to suggest including: good documentation puts things together in usable sequences for people. It doesn't just explain each option or call in isolation. When something change, the first task of the documentation people is add or change the necessary information about that individual feature, but then something should try to go through tutorials or other documents and try to think of the ripple effects of the change. Entire procedures that are currently documented may be no longer necessary. [I added a paragraph about this. Thanks! -K] * Chapter 7 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-06 Fri 23:10 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Road repair metaphor (page 142): I love this metaphor, and will think of it the next time I'm crawling along Route I95. But you might be unnecessarily pessimistic. Do parallel development tracks really discomfort anybody? Open source projects maintain a clean, stable release while creating a new branch (or several) to work on updates. Why say that everybody slows down in order to allow development to proceed in parallel? [Yep, it definitely slows it down. I can supply examples without end :-). If stabilizing release branches had no cost, there would never be discussion or dissent about creating them. In practices, there are costs and they are usually noticeable to all developers (especially in open source projects). -K] "Since the first edition of this book..." (footnote, page 144): Don't talk about the differences between the first and second editions in this book, unless you have a critical point to make. (For instance, you can distinguish between editions if you offered advice in the first edition that is invalid in the second because of changes in the environment.) I don't think this footnote is needed. Say in the text what's current, bring everything up to date. [Got rid of the edition comment, but kept the footnote. -K] Major, minor, patch (page 145): Explain the sometimes fluid difference between these concepts first. Then explain how the canonical three-part numbering scheme reflects those concepts. Currently, you do the opposite: describing the scheme before the meaning. [Too hard to reverse the order -- it's a good idea, but it also introduces problems of its own. I'm sort of counting on the fact that only people seriously concerned with getting version numbers right will even read this section, and those people are the sort of reader for whom presenting the scheme first and then tying it to the concepts will work okay. -K] "...regular development work happens..." (page 148): I am confused about the difference between the main branch and the others. What is "irregular" about working in another branch? You need to distinguish the different work performed on different branches. [Fixed, thank you. -K] "...fairly strict branch management..." (footnote, page 149): I don't know what this is. Hopefully, an earlier section defined what you mean by "strict branch management." You have to indicate what you mean by this. Is it just maintaining branches for each type of work and making sure each commit goes to the branch where it should go? [Explained it better, thanks. -K] Digital signing (page 157): this may need a little more explanation. Even I, who have a general sense of how the web of trust works with GPG, am confused about how average users will use it to reach the developers who signed the release. Do you expect people to build up enough personal connections to make use of the web of trust? [I can't fully explain it in this book, as it's too big a topic, but mention it earlier now and have added pointers to some resources. -K] "The purpose of all this signing and checksumming..." (page 157): I like to put purposes near the beginning of the section, not the end, because you are explaining why this section is important to read. [Good point! Handled in the above change. -K] Planning Releases (pages 160-161): Back in Chapter 5 (as well as in one of your ORM reports) you discuss the strategy of doing work in a separate branch to ensure a company can release what customers want on time, and then merging it back into the open project. Couldn't that be done here? It's not a complete substitute for getting what you want into the open project, but it's an alternative. [Ah, thanks for noticing the connection. Done. -K] Jeffersons' University (page 161): Is this an ethical and appropriate model for persuading free software developers to support one person's plan? Suppose Jefferson really had a stupid idea? Wouldn't you want free-wheeling discussion before anything is "set in stone" as you call it? Of course, before anyone makes a suggestion, it's always good to do some research and present a clear plan about its feasibility, but the purposes isn't to railroad discussion. [I made a minor modification to emphasize that the plan should be a good one, but yes, basically, I think this is an ethical and appropriate model. IMHO freewheeling discussion is rarely good *in the specific case of planning releases of an open source project*. It's good in many other situations, just not that one. -K] * Chapter 6 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-07 Sat 00:37 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Some interesting comments, nothing too disruptive I think. Per one of my principles, let's provide a broad overview of the topic (communications is a big topic!) at the start. For the first two or three paragraphs, I would remind readers what an open source project must do--recruit developers and users, motivate people, allow free-flowing discussion while reaching decisions, etc.--and then proceed to the types of communication required. The importance of writing well is a secondary topic, and could be a section following these few introductory paragraphs. [Good idea; done. -K] I wonder whether you have devoted enough material to the media (mailing list, web site, FAQ, etc.) a project uses to do communications. You introduce a lot of these in Chapter 2 and descibe them on a technical level in Chapter 3. Maybe these are enough; I'm not sure. Chapter 6 assumes that all these are in place and talks about how to maximize their value. I would consider listing the important basic blocks of communication again. [I think they'll remember, or consult back in Chapter 2. This is partly because it's very unlikely that any of that infrastructure will be unfamiliar to a reader anyway -- most people reading this book know about wikis and Slack (if not IRC) and mailing lists anyway. -K] By the way, a friend of mine has a T-shirt reading, "Hyperbole is the greatest thing ever." [I want that T-shirt more than anything else! :-) -K] Structure and Formatting, page 115: I cheered when I read your first paragraph about writing with proper grammar. From my own experience over the decades, I'd like to suggest another point you can make (regarding "arbitrary"): proper grammer and word usage is critical to minimizing ambiguity. Ambiguity can be very destructive in technical material (and certain other publications, such as legal ones). And little things such as run-on sentences, where it's not clear what's cause and what's effect, can create this dangerous ambiguity. No one can be perfect, but writers should do the best they can and reread their own work to look for ambiguity caused by mistakes. [Done, and...] The rest of this section could be a bulleted list, each paragraph after the second becoming its own item. [...done. -K] Subject lines, page 116: I don't know whether my observation here is on-topic, but I'm frusrated to find that Google Mail doesn't let you change the subject line when you press Reply or Forward. I don't know whether other mailers have the same problem, but a lot of people use Google Mail. When I want to change the subject line, I have to launch a new thread (which I may or may not want to do) and manually cut and paste addresses and the text of the email. [It does allow it. I'm pretty sure I sent you an email explaining where it's hidden in their UI. -K] Real names, page 118-119: I like your clever suggestion that people who want to remain anonymous can invent a real-seeming name. Women (and perhaps certain ethnic groups) have a particular need to hide their identities because they can be harrassed quite severely, and their contributions can be devalued. They may try to choose "neutral" names. I don't know whether this is worth saying--you already grant them the right to hide their identities. [It's a good point, but IMHO not worth the space. Anyone who wants/needs to do that sort of identity hiding has already figured this out, and will understand how that fits in with the advice here. -K] Avoiding Common Pitfalls, page 121: Can you add a sentence or two after this heading? Our production team has (or used to have) a rule against putting two headings in a row. I concur, finding that this looks bad. And there's almost always something general one can say to tie subsections together. As encouragement, here's a suggestion: the subsections here revolve around the idea of increasing productivity during discussions. You could find a couple sentences to say about that. [Done. -K] "Me too" posts, page. 121: I'm not sure I'd encourage people to post empty encouraging messages--every message takes up a little bit of other people's time, and if the mailing list contains a lot of content-free messages, readers are discouraged from reading it. Your next section talks about signal/noise ratio, and I think that applies here too. Unless people are voting, I'd avoid extra messages that just convey encouragement. When I want to convey encouragement, I try to find something extra to say that "adds value." [Added some clarification about when it's okay to do a "me too" post. -K] Holy Wars (pages 124-125): I have my own approach to holy wars (man, don't you see lots of those during this election season?). It may or may not be useful to you--you can ignore this if you want. I think holy wars stem from different basic values. The idea of "values" is almost defined by these being unarguable. You are pro-life or pro-choice, that's it. And sometimes people do overlap in their values (most people are partly pro-life and partly pro-choice) but different groups emphasize a value more than others. So people may have radically different values, or may simply place different value on each of their shared values. Take the GPU vs. BSD bruhaha: both sides value freedom of choice and efficiency, but they place different emphases on each. In any case where values clash, argument is useless because values lie beyond rationality. My two cents. [I agree, but probably it won't help the reader much to go into that here. This section isn't about the philosophical causes of holy wars, but just about how to avoid starting them or fanning the flames. -K] The "Noisy Minority" Effect (pages 125): It might be worth acknowledging that the minority is sometimes right. In politics and social policy, we have plenty of examples of this. (Most white Americans in 1950 thought that blacks didn't deserve equal political rights, for instance.) If the merits of a proposal can be discussed dispassionately (which can't be done during Holy Wars, for instance, because values are not subject to rationality), the number of people who support each side isn't really important. I may be idealistic here. [That's what I love about open source: it's okay if the right side doesn't win, because they can always fork if they really want to. (Whereas in 1950s America, a black person couldn't, you should pardon the expression, fork the lunch counter or the drinking fountain or any of the countless other bits of physical and social infrastructure that were arranged to keep white people on top.) So I don't want to address here the sitaution of the minority being right. This section is specifically about how to deal with noisy minorities who are abusing project procedures to prolong a discussion that should be settled, rightly or wrongly, by now. -K] Difficult People (page 126), would you feel comfortable mentioning the discussions in The Art of Programming? It's up to you. [Did you mean "The Art of Community" or "Team Geek"? The only other thing that I know of with a title close to that is Knuth's "The Art of Computer Programming", but you surely didn't mean that. In any case, I don't want to cite another source unless either I've used it or it says something I don't say here. The former is not the case, and AFAIK the latter is not either. -K] Conspicuous Use of Archives, address for archives (page 130): in an earlier chapter, you said archives often move--that seems to contradict your "forever" URL promise here. [I added some material in "linking-to-emails" about why archives sometimes move even though it's rarely desirable that they do so. -K] Treat all resources like archives (page 131): Consider using the list to contain both the purpose of the FAQ and the implied way to handle, instead of having the purposes in the list and the implied way to handle the FAQ in the paragraph that follows. (And the list should probably be bulleted.) I think the points could be absorbed by readers more easily if each purpose is tied right to your conclusion about what to do. [Spot-on point, thank you. Done. -K] "policing" (page 133): This is an overly harsh word, as is evidenced by your disclaimers in parentheses. Say "monitoring" instead. [Done. -K] "r12908" (page 133): isn't this format also the way the revision appears in svn command lines? A good reason to settle on it as a convention. [Yup, though the tooling support appeared later, after the convention was already decided on. -K] Announcing Security Vulnerabilities (page 136): Sometimes it's hard to tell whether a bug makes a piece of software less secure or just causes bad outcomes. I don't know whether you should discuss this here, because it's a highly technical (and language-dependent) topic that goes beyond the scope of the book. Perhaps a paragraph describing the difficulty of deciding what's a security vulnerability is worthwhile. To some extent, this is a communications issue, and therefore relevant to the chapter: a project wants to help users understand which bugs are security vulnerabilities. [I think I don't want to wade into that particular snowstorm here. If the project has difficulty deciding what constitutes a security vulnerability, there is probably little guidance this book can give them. -K] Some of this section may be outside the scope of the communications chapter. This chapter isn't about how to handle and fix security flaws; it's about communications. I can see how all the material could arguably stay in this chapter, but perhaps there's a more appropriate chapter for some of the security material. [Well, most of this material is about communications, in the end. There isn't really a better place for this material, as far as I can see, so I just left it here. Not perfect, but it'll do. -K] * Chapter 3 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-07 Sat 14:31 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Move Canned Hosting (page 40) before Web site (page 39). I suggest this because canned hosting is an all-in-one umbrella solution that covers most of the other, individual tools. It makes sense to consider canned hosting first and do the others only if you find a reason to reject it. [I tried reversing them, but it didn't work as well as I thought. By coming first, the web site section explains what the web site needs to do; then the canned hosting section discusses one possible way to address those needs. I made some changes to make the linkage clearer. -K] "Be sure to use moderation..." (p. 46): Consider making this a note. That makes it stick out and be more visible, which I think it deserves. [Done. -K] Two fantasies (page 50): this also could be a note. I believe one can assign a title to a note, but even without the title, these two paragraphs make a good note. [Done (apparently I did it a while ago). -K] Footnote 7 (about Michael Bernstain) and footnote 8 on Siesta: why not incorporate these into the text for the new edition? [Done. -K] Archiving (page 50): I suggest a short introductory paragraph listing the important aspects of archiving: that they allow messages to be retrieved later (and I've often solved a problem by accessing a message casually posted by some stranger), that they provide a history that's valuable to new users coming up to speed and to maintainer, perhaps other advantages. [Done. -K] Mailman, "As of this writing, in late 2013..." (page 52): clearly a section of the book you didn't look over and update. [Fixed. -K] Version Control, "it is a communications mechanism" (page 52): while version control is this, I agree, it is more fundamentally a piece of software that assures the integrity of software. I would say this first, followed by the communications rols. Version control (if backed up properly) ensures that the software is never lost, that its history and former states can be reconstructed, that each contributor's contributions can be recorded and acknowledged, etc. [This is true, but the part that matters for this book is more the communications aspect. The fact that it ensures software integrity is not particularly important to open source in the way that the other aspects are. -K] Terminology (pages 53-56): I suggest adding an entry for "reversion", which you refer to later. [Done. -K] push and pull (page 53): I don't want to add extra verbiage to your introduction to version control, but it may be worth mentioning somewhere (right near the beginning) that version control systems allow people to create a copy of their software on their local systems--a sandbox (or the terms you seem to prefer, clone or working files). Then the concepts of push and pull make more sense. [Thought about it, but... slippery slope. I think I'll leave it as is. -K] Authorization (pages 59-60) A complex area. This is a good section, but it leaves unclear (to me, at least) whether to give access to the whole project to a new, competent committeer. You seem to say that they should have access to the whole repository, but the last paragraph pulls back and suggests that you should somehow restrict people's access. How? [Yup; it was just written unclearly. Fixed. -K] Wikis, page 68: per my usual principle, state the positive impacts and possibilities first, and then how they can "go bad." By the way, I think another problem with wikis is that they don't get updated promptly, and therefore that readers come to distrust them as canonical sources of information. [Done. I agree with you about that problem, but I think it's already implied in the discussion in the section. -K] * Chapter 4 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-07 Sat 15:26 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :END: Forkability (pages 72-72): I have two general suggestions for material to add. First, what I've heard of the various BSD projects is very sad. I mentioned this also in my comments to Chapter 1. I believe that the proliferation of *BSD projects could have been avoided if the maintainers knew the kind of open source collaboration culture that eventually developed in other projects. They had numerous forks, and created confusion as well as bad vibes. Might be worth mentioning. [I've heard this too, but I don't have enough first-hand knowledge nor primary sources to want to discuss it in the book. In general, when I talk about specific projects, I like to have reams of evidence so I'm sure that what I'm saying is accurate. -K] Second, there is a process that GitHub calls forking. Someone (maybe you) told me that it's not forking in the same drastic sense that the GNU compiler or Emacs forked. That might be worth mentioning, because other readers may be confused. GitHub presents forking as a good thing (and I think it may be part of the larger Git culture as well), but it's a much less conflicted process. [I added this distinction a while ago, in Chapter 8, but have now added links to it from relevant places in Chapters 4 and 5. -K] Approval voting, page 76: I see two other reasons to avoid complex voting systems: people are less likely to understand them and therefore to trust them, and people are less likely to use them optimally because they require training. [Added this point, thanks. -K] Footnote on Software Freedom Conservancy, p. 80; this is a disclosure, not a disclaimer. [Good point -- fixed! -K] * DONE Chapter 5 (Andy Oram) :PROPERTIES: :ARCHIVE_TIME: 2017-01-08 Sun 17:08 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Andy Oram comments :ARCHIVE_CATEGORY: todo :ARCHIVE_TODO: DONE :END: Lots more comments on this chapter than usual, including a suggested name change and some reorganization. This chapter doesn't hang together as well as the previous ones. I feel that, using the unifying thread of money, you throw together a bunch of issues that perhaps don't really go together. Most of the chapter could go better under the title "Participating as a Business or Government Agency." The current title reflects the fuzziness of the topics in the chapter. When you talk of organizations, you make it sound like the chapter covers infrastructure, which was the topic of Chapter 4. And if you talk about money, people will think you'll talk about fund-raising, and then you have to explicitly say you won't. (Actually, you have one section about it; Crowdfunding and Bounties. Perhaps there's another chapter that could go in.) [Made the title change. I kept the disclaimer about fund-raising, though, because so many people think this book is going to explain that that I feel it's necessary to put a notice, in the place they're most likely to look, that it's not going to do that. -K] I think that most of the chapter could stay together with the new title I suggested. A few other changes would follow: * The "Funding Non-Programming Activities" section might be worth rethinking. You could orient it around "things that need to get done and nobody enjoys doing" instead of money. Perhaps it should be broken up. Quality assurance may fit well in this chapter, whereas conferences might go elsewhere. Marketing is also a topic that goes beyond the question of who pays. [I don't know... I re-read it in context, and while there is a certain slightly-random quality to its placement, it fits well enough and I can't think of anywhere more appropriate to put this stuff. I did add one more item, about donating security audits, and perhaps the presence of another item in the list will help justify the list more. -K] * Don't Bash Competing Open Source Products and Don't Bash Competing Vendor's Developers look like communications issues, not business issues. They could go in the communicatiosn chapter. Of course, I just recommended that you bash the BSD projects... [ :-) I moved the former to Chapter 6, but kept the latter here (albeit renamed), because the latter is more about corporate commercial behavior than about developer communications. -K] * Foster Pools of Expertise in Multiple Places seems like a topic for another chapter too. (I'm not sure which one, maybe Chapter 4.) [Hmm, no, I think this really is about organizations and how they interact with open source projects, and therefore belongs here. It's not about fostering multiple sources of expertise *within* the project; it's about fostering multiple sources of expertise to provide support for a user of the project. -K] * Establish contact early with relevant communities: looks like a Chapter 4 topic. [There's a stronger case here for moving it, but I still think it belongs here more than in Chapter 4. Again, this is primarily about how a centralized organization should use its resources to make an open source project succeed. -K] Now, on to comments about specific sections: Augmenting services (page 84): there may be a better term for this item. It's more like "Ensuring maintenance of infrastructure" because the open source project is infrastructure for the company. [Agreed; fixed. -K] Donations (page 85): this should not be here, because it's not a motivation for supporting an open source project. [Yeah, weird, why did I even have it there? I've just removed it. -K] "In addition to..." (page 86): I think you intended this paragraph to be broken into a list, and for some reason the formatting didn't happen. It should be a variable list. [Yup, good call. Done. -K] "disclaimer" (page 90): Again, this is a disclosure. [Fixed again, thanks. -K] Benevolent Dictator (page 91): I like your point in this paragraph, but I suspect it's rarely followed. My impression is that if a company starts a free software project or takes control of the funding for one, the company keeps final say to itself. I believe that's true at Canonical, for instance. (On the other hand, in Providing Hosting/Bandwidth you suggest that some companies do the opposite--they try to milk a project for good PR without really participating.) [I've tweaked the conclusion of the paragraph to bend it in the direction of your point slightly. -K] "Will other developer resent..." (page 92): I think there may be another issue to consider (although this section is already rather long): not so much resentment as confusion about what types of development are worth paying for. Probably the company should explain why it chose to pay for a certain feature instead of just going through the consensus-building process (which it has to do anyway to get the feature accepted). Probably the company has a deadline to meet a customer demand, and that's worth stating. Otherwise, contributors who work for free may wonder whether they could get the company to pay for their work. [Usually companies do state this, and hopefully the reader will remember the advice from "Be Open About Your Motivations" -K] "Update Your RFI..." (pages 93-94): I can tell that each of the points in your list is based on real abuses that companies carried out in government work. That might be worth mentioning. [Done, thanks. -K] Dirk Reiners quote: Could you ask him what he means by "His case was even better"? What "case" is this? Better than what? [I removed that second paragraph from the quote; it wasn't necessary anyway. -K] Total cost of ownership (page 101): Another point is that the costs of proprietary software tend to outstrip open source if you look ahead long enough. I remember how the city of Munich did a TCO analysis that looked five years into the future, and decided that MS Office was cheaper than OpenOffice.org. (They switched anyway, as I'm sure you know.) But five years is an artificial cut-off point--the costs of MS Office keep getting more out of line over the years. (This discussion is also relevant to the item "Open source is cheaper" on page 105, so I'm not sure whether it's worth including in one place or the other.) [Added that point in. Thank you. -K] Dispel Myths Within Your Organization (pages 104 ff.): Perhaps divide these into unfairly positive myths and unfairly negative myths. Then people can anticipate what you're criticizing. Here is three other myths worth citing: 1) Open source is less secure, because malicious users can peruse the code. 2) All bugs are shallow. 3) We can casually copy open source code into our code. [Good ideas all -- done. -K] Foster Pools of Expertise in Multiple Places, page 106: Is it worth talking here about certifications, such as LPI? I don't know what you think of them. Most American programmers (at least in open source) scoff at certifications, but they're a big deal in Japan, Brazil, and some other places. [I don't think I know enough about them to talk usefull about them. -K] Don't Let Publicity Events Drive Project Schedule (pages 107-108): the last paragraph discourages companies from forcing communities into pre-planned schedules. But several successful projects, notably Ubuntu, do that. I think this paragraph may be overly idealistic. [This is really an example of everyone -- Canonical and the Ubuntu community -- being on board with time-based releases. I've adjusted the text to mention this exception. -K] The Key Role of Middle Management (page 108): It might be worth explaining the typical relationship between a manager and an open source project. Perhaps a manager has a one-to-one relatioship with a project: she's responsible for the company's contribution to the project and is really a member of the open source project herself. That's a relatively simple scenario. I suspect that often a manager is in charge of some internal corporate project that is not open source, and is also directly responsible for programmers working part-time or full-time on an open source project. That's more difficult and takes a lot sensitivity on the part of both the managers and the programmers. [I think someone reading this section will already have enough background to figure whether/how their situation matches up with what's discussed in the book. Also, the last paragraph of the section does touch on the question of whether the manager has a personal relationship with the open source project. -K] Innersourcing (pages 109-110): Although we agree that this is a timely topic that should be in the book, it sticks out as unrelated to the rest of the chapter. The chapter is about business, but that doesn't mean this section goes with the others. It might be better as either a sidebar or its own appendix. One way to integrate the section with this chapter better is talk about innersourcing as a stepping stone on the way to open sourcing, or as a follow-up to doing open source projects that train the company in open source processes. [Heh. You caused me to re-read the section, and discover that I was quite pleased with it :-) (but also that it had a few typos and wrong-word bugs, which are now fixed). In the end, I think I'll leave it here. It fits the theme of discussing the relationship between open source and organizations, especially with the new chapter title. -K] Hiring Open Source Developers (page 110): In the Huawei report, you ramped up very nicely by discussing why a company would want to hire developers with a particular expertise, and then how to do it. A couple paragraphs here about the benefits of hiring developers out of an open source community would be helpful--although you also discuss hiring new programmers to join the community. [Good point. New section "Hiring for Influence" now covers this. -K] Evaluating Open Source Projects (page 110): You might mention the term "project maturity," which appeared in a companion book to yours: Open Source for Businesses. [Done, thanks. -K] * FIXED: Why is the output="printed" conditional not working? :PROPERTIES: :ARCHIVE_TIME: 2017-01-09 Mon 11:07 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Web site and build infrastructure :ARCHIVE_CATEGORY: todo :END: For example, in Chapter 8 there is this conditional: (see in ) and yet the HTML output produces (with links, of course) this... (see the section called “Trademarks” in Chapter 10, Licenses, Copyrights, and Patents), ...in en/forks.html. What's up with that? * BUG: DocBook->PDF via FOP continually breaks, totally unmaintainable. :PROPERTIES: :ARCHIVE_TIME: 2019-06-15 Sat 18:33 :ARCHIVE_FILE: ~/src/producingoss/todo.org :ARCHIVE_OLPATH: Web site and build infrastructure :ARCHIVE_CATEGORY: todo :END: Wow, I'm so tired of this. In theory, DocBook is convertible to PDF. In practice, you need a team of NASA scientists to get it working. At least, the method used in 'lang-makefile' here, with Apache FOP, has never stayed working for more than a year at a time as far as I can remember. http://www.dpawson.co.uk/docbook/tools.html has some alternatives; search for "Off the top of my head, I know of the following ways to transform DocBook XML into PDF, with open source/free/semi-free software". See also http://www.scons.org/doc/HTML/scons-user.html#b-DocbookPdf, and http://lwn.net/Articles/661778/ re 'dblatex'.