\documentclass[portrait,20pt]{foils} \usepackage{amsmath} \usepackage{amssymb} \usepackage{amsthm} \usepackage{color} \usepackage{subfigure} \usepackage{graphicx} \usepackage{hyperref} %\usepackage[UTF8]{ctex} \title{Software Project Management} \author{} \date{} \MyLogo{Copyright \copyright 2018, 2019, 2020 Hui Lan} \begin{document} \maketitle %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Syllabus} \begin{itemize} \item Instructor: Hui Lan \item Email: lanhui AT zjnu.edu.cn \item Course home page: http://lanlab.org/course/2020s/spm/ \newpage \item Recommended textbook: \\{\bf Karl Fogel}. Producing Open Source Software - How to Run a Successful Free Software Project. 2017. Available online at \url{https://producingoss.com}. Most of the course materials are from the above textbook. \includegraphics[width=0.50\textwidth]{fig/oss_cover} \newpage \item Grading: \begin{itemize} \item Quizzes - 15\% \item Project - 25\% \item Final Examination - 60\% \end{itemize} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Quizzes} {\bf Number of quizzes}. I will post 7-10 quizzes throughout this semester on our course home page. Each quiz will be posted one week before its due date. You should check our course home page at least once a week to not miss any quiz. {\bf Submission instructions}. Class 02395 (consisting of students from Software Engineering (Chuyang), Computer Science and Technology, and Computer Networking) - submit through \href{https://www.duifene.com/}{Duifene}. Class code: {\bf AKVCJ}. Class 02396 - submit through \href{http://118.25.96.118/nor}{LRR}. Course code: {\bf CSC322}. Graduate students - submit through \href{http://118.25.96.118/nor}{LRR}. Course code: {\bf CSC1102}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Course Project} For people from Software Engineering (English), you have already implemented OMG (Oh My Genes) and improved OAPS (Open Access Publishing Service). Therefore, you could pick one of them to manage for this course. For people from Software Engineering (Chuyang), you have already spent a lot of time on implementing \href{http://lanlab.org/course/2019s/se/homepage.html#project}{a software} for analyzing condition-dependent gene expression scatter plots. So you will continue to work on (i.e., manage) that. For other people, you will manage LRR. You must form project groups by March 2. The group size can be 1, 2, 3, or 4, depending on your situation. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Final Exam} Something I would talk later in this semester. For now, I think that it will be a closed-book, 90-minute test. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Software Project Management Concepts} Application of management activities - planning, coordinating, measuring, monitoring, controlling, and reporting - to ensure that the development and maintenance of software is systematic, disciplined, and quantified. {\it dis·ci·plined: showing a controlled form of behavior or way of working.} {\em Textbook management looks so easy and real-world project management is in fact so hard. -- Barry W. Boehm} {\bf Capable people are no longer available.} For example, the LRR's original author is no longer available to work on the project. He has other more important commitments. Some people (e.g., Jin Mingyi), maybe also including the original author, think LRR is not maintainable. {\bf Old plan becomes outdated very soon.} You have a plan but you continuously get distracted by additional ``requests''. A flood of them is a phenomenon called {\em request creep}. \begin{itemize} \item A request to add ``a few small capabilities'' to the product without changing the budget or schedule. \item A request to take on some personnel who are between projects and find something useful for them to do. \item A request to reduce the scope of design review (in order to make up some schedule). \end{itemize} Should you simply be a nice guy and accommodate any request? No. You should think carefully about the impact of the request. You should be able to negotiate a corresponding change in plans, schedules and budgets. Steps I suggest you to follow. \begin{enumerate} \item Politely say ``No''. \item Tell that I am willing to help if I am not that busy. \item Analyze the impact of the additional requests on my current schedule. \item Ask for more money or time, or both. (The management board would usually agree as they have already invested a lot, as long as your counter-requests are reasonable.) \end{enumerate} {\bf Other difficulties}. Programmers with various background and various personal goals. Programming languages. Licenses. Development processes. Infrastructures. {\bf Solutions}. \begin{itemize} \item Organizational. \begin{itemize} \item Get a lot of money. Get a lot of resources. Get a lot of support from government and funding bodies. \item Make sure employees write clear documentation and self-documenting code before they leave the project. \item Have a requirements management procedure. \item Incentives. Make sure hard and productive workers are rewarded and project parasites are not rewarded (if not downgraded). \item Make sure useful developers don't get marginalized due to personal idiosyncrasy. \end{itemize} \item Motivational. Understanding developers' motivations is the best way — in some sense, the only way — to manage a project. \begin{itemize} \item Establish a shared belief that people can do better together. The goal of management is to make people continue to believe so. \item Get deep personal satisfaction from doing one's best work, and from appreciating and being appreciated by one's peers. \item Coercive techniques don't work. People should feel that their connection to a project, and influence over it, is directly proportional to their contributions. \item Monetary and non-monetary motivations. Extrinsic motivation and intrinsic motivation. Overjustification Effect. \item {\bf Goodhart’s Law} - when a measure becomes a target, it ceases to be a good measure. Example: customer retention, tester bug reporting. Danger: people game the system. \end{itemize} \item Set standards for communications. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Proprietary Software} {\em proprietary: relating to an owner or ownership.} The software is owned by a company, which sets out many restrictions on use, modification and distribution. We need to pay (explicitly or implicitly) before we can use it. Understandable because the company has spent a lot of money and made a lot efforts to develop and update the software. Understandable because the company does not want its competitors to take advantages of its source code. {\bf Mini assignment} (no submission required): read a proprietary software license and figure out the described restrictions. Must be protected by law. Good for society as the company makes profits and creates jobs. For example, the Berkeley Software Distribution (BSD) group did not consider proprietary software a social evil. But proprietary software can be bad for society if it goes too far. ``The rule made by the owners of proprietary software was, {\em If you share with your neighbor, you are a pirate. If you want any changes, beg us to make them}.'' -- Richard Stallman. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Free and Open Source Software} These software are usually free of charge. Many have very high quality. You can read, modify or redistribute the source code, if the software is free or open source. For example, you can browse the source code for Ubuntu, Lubuntu and Xubuntu. Can you browse the source code for Windows 10? Free and open-source software are quite prevalent today. Ubuntu, Firefox, Emacs, Nano, Apache Server, etc. {\bf Free software emphasizes ideology}. A noble cause. For example, \href{https://www.gnu.org/education/edu-schools.en.html}{Why Schools Should Exclusively Use Free Software?} Representative: Richard Stallman. Four Essential Freedoms (run, study, modify, redistribute). License: \href{https://www.gnu.org/licenses/gpl-3.0.en.html}{GPLv3} (approved by both FSF and OSI). Any derivative work must be distributed under GPL too. Make freedom contagious. %Creative Commons Attribution-ShareAlike. Share. Remix. Conditions: Attribution. Share Alike. {\bf Open-source software emphasizes practicability}. More practical. Great convenience. Community driven development model. \href{https://opensource.org/licenses/category}{Various open source licenses} %% {\tiny %% \begin{verbatim} %% 9. License Must Not Restrict Other Software %% The license must not place restrictions on other software that is %% distributed along with the licensed software. For example, the %% license must not insist that all other programs distributed on the %% same medium must be open-source software. %% \end{verbatim} %% } ``Given enough eyeballs, all bugs are shallow.'' {\bf The difference}. The difference between free and open source is largely on philosophical matters. {\em The two terms describe almost the same category of software, but they stand for views based on fundamentally different values. Open source is a development methodology; free software is a social movement. -- Richard Stallman} {\bf The similarity}. \begin{itemize} \item You can modify the code. \item You can redistribute the code, modified or original. \item No warranties. Use it on your own risks. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Overhead at the Beginning} Opening up a project can add whole new sets of complexities, and cost more in the short term than simply keeping it in-house. Extra work (or pure overhead at first) for the people least familiar with the project to get started: \begin{itemize} \item Arrange the code to be comprehensible to complete strangers. \item Write development documentation. \item Set discussion forums. \item Answer questions for potential developers. \item Set other collaboration tools. \item Set a project home page. \item Automate compilation, packaging and installation. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Benefits in the Long Run} Significant organizational benefits - let the outside world know what you are doing. A low-cost form of advertisement. Global influence. Benefits greatly outweigh the costs. For example, Microsoft Loves Open Source (treat open source a development methodology and business strategy). {\bf Reap the benefits}. {\em The sponsor only pays a small number of expert programmers to devote themselves to the project full time, but reaps the benefits of everyone's contributions, including work from programmers being paid by other corporations and from volunteers who have their own disparate motivations (for moral reasons, their employer paid them to, or because they're building up their résumé).} Example: \href{https://hadoop.apache.org/who.html}{Huawei on Hadoop}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Browser Wars} Non-trivial and incompatible interfaces: ftp, telnet, email, gopher, lynx. Limited to people with reasonable programming skills. Netscape's contribution: first made Internet accessible to average people. Netscape versus IE in early days (mid and late 1990's). \begin{itemize} \item Netscape. \begin{itemize} \item 1993. Primitive Mosaic browser (multimedia web pages). \item 1994. Mosaic Communications Corporation, then Netscape Communications. Mosaic Netscape 0.9, then Netscape Navigator 1.0. Over three-quarters of the browser market within three months of launching. From 5 to 2000 programmers. Virtually no competitors. \item 1995. IPO, market value of 2.9B. A highly innovative product. Thousands of employees. \item 1997. Netscape Communicator: Netscape Navigator, Netscape Address Book, Netscape Mail, Newsgroups, and Netscape Composer. \item 1998. BAD YEAR. Netscape Communicator 5.0 release delayed (and never released). Acquired by AOL for 4.2B. \item 2000. Netscape 6.0. \item 2002. Netscape 7.0. \item 2003. AOL closed the Netscape department, outsourced it to Mercurial Communications, a Canadian Company. \item 2007. Netscape Navigator 9. Market share: IE 77.4\%, Firefox 16\%, Netscape 0.6\%. \item 2008. Shut down by AOL. No more support. No further releases. \end{itemize} \item IE. \begin{itemize} \item 1994. Microsoft talked to Netscape about licensing browser technology. Declined by Netscape. \item 1995. Microsoft IE 1.0, 2.0 \item 1996. IE 3.0 \item 1997. IE 4.0 \item 1998. IE 5.0. Consistently better product, in terms of speed and stability, bundled with Windows OS (dominating desktop market). Free of charge. \end{itemize} \end{itemize} %All browsers https://www.techpaparazzi.com/how-web-browsers-looked-from-in-90s/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Coopetition} Publish standards. Win partners and share the market and profits. General Electric: EDI. Sun: Java applets. Informix: database access through browsers. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Jamie Zawinski and Joel Spolsky} ``In January 1998, Netscape hit one of its blackest periods -- the first round of layoffs… At this point, I strongly believed that Netscape was no longer capable of shipping products. Netscape's engineering department had lost the single-minded focus we once had, on shipping something useful and doing it fast. That was no longer happening. Netscape was shipping garbage, and shipping it late.'' - Jamie Zawinski, Former engineer, Netscape. ``Now the problem here is that the product's direction changed utterly. Our focus in the client group had always been to build products and features that people wanted to use. That we wanted to use. That our moms wanted to use. 'Groupware' is all about things like 'workflow', which means, 'the chairman of the committee has emailed me this checklist, and I'm done with item 3, so I want to check off item 3, so this document must be sent back to my supervisor to approve the fact that item 3 is changing from 'unchecked' to 'checked', and once he does that, it can be directed back to committee for review.' Nobody cares about that shit. Nobody you'd want to talk to, anyway.” - Jamie Zawinski. ``Open source does work, but it is most definitely not a panacea. If there's a cautionary tale here, it is that you can't take a dying project, sprinkle it with the magic pixie dust of ``open source,'' and have everything magically work out. Software is hard. The issues aren't that simple.'' - Jamie Zawinski. ``The old mantra 'build one to throw away' is dangerous when applied to large scale commercial applications. If you are writing code experimentally, you may want to rip up the function you wrote last week when you think of a better algorithm. That's fine. You may want to refactor a class to make it easier to use. That's fine, too. But throwing away the whole program is a dangerous folly, and if Netscape actually had some adult supervision with software industry experience, they might not have shot themselves in the foot so badly.'' - Joel Spolsky, Software engineer, and co-founder, Glitch %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Lessons from the Competition} {\bf Netscape's mistakes}. Poor product, poor product decisions, product direction. Became too big. Stopped innovation. {\em Feature creep}. Kept adding features with ``no break, no time for rearchitecture''. Consequences: (1) Messy codebase. (2) Buggy product. \href{https://yujiri.xyz/software/features}{Features are costs}. %Feature bloat (too ambitious). Bloatware. Groupware. Lost single-minded focus. 5.0 never released. 6.0 released prematurely after 3 years (under management pressure). %Outdated browser core. MISTAKE. Try to do everything from scratch (in year 1998). Anti-Microsoft. Crufty, complicated code. %JOEL SPOLSKY https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/ {\bf IE's upper hand}. Pricing: always ``Free of charge''. Giant Microsoft could afford it. ``Destroying that market''. Distribution: bundled with Windows 98. Most people \href{http://www-inst.eecs.berkeley.edu/~eecsba1/sp98/reports/eecsba1c/pj1/freq.gif}{do not switch browsers}. PC makers are locked in to using Windows 98. Developer support. Not that bad in the beginning, and consistently better afterwards. Frequent releases. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Status quo} Netscape Navigator evolved to Firefox (open source managed by Mozilla Foundation). Internet Explorer evolved to Edge (using Chromium core). Even more browsers nowadays: Firefox, Chrome, Safari, Edge, Opera, UC Browser, QQ, 360, Sogou, Baidu, etc. Which one are you using now? Which one will win? I am using Edge now. (I used Firefox many years.) I think unless you have a clear advantage in your product, it is very hard to compete with a company who bundles its product with its operating system. For most users, why do they need to bother with downloading something (usually big) that is not far superior to the default one which is free? % 95\% of the users are laymen. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Starting from Scratch} How to treat old code wisely? Throw it away? Why do programmers want to start from scratch? Fundamental Law of Programming (Joel Spolsky): It’s harder to read code than to write it. Starting from scratch can be an absurd strategy or behavior. Startup company killer: Build one to throw away. Big misconception: New code is better than old. Reasons; \begin{itemize} \item You cannot guarantee that new code is better than old code. \item When we add code, we add functionality, and bugs as well. \item While old code looks ugly, new code can be even worse. \item You may make old mistakes again, and make new mistakes. \item Old code has been used, tested and fixed. New code has not. This means tremendous efforts and time (usually invisible to you) have been invested in the old code. That's money. \item Old code: maybe the fix is just one line of code, or just a few characters. But that demands tremendous efforts. Throwing away code is throwing away the efforts, sometime years of programming work. \item (Old code) doesn’t acquire bugs just by sitting around on your hard drive. - Joel Spolsky. \end{itemize} {\bf Software years}. Even if your new code is better, you may be several software years behind, and therefore, lose market. % Things You Should Never Do, Part I https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Use Branches to Avoid Bottlenecks} Branches are valuable because they turn a scarce resource — working room in the project's code — into an abundant one. Branches are cheap to make. Copy the castle and add a drawbridge in isolation. Make Pull Requests, ask for review, and merge (when all reviewers are happy). Isolate and stabalise the release line to the development line. Use branches liberally. Most branches should merge their changes back into the main line and disappear, as soon as possible. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Pull Requests} A \underline{pull request} is a request from a contributor to the project that a certain change be "pulled" (merged) into the project. Once a contribution arrives, it typically goes through a \underline{review-and-revise} process, involving communication between the contributor and various members of the project. The moment when a code change is merged to the project's master branch is when it becomes officially part of the project. 99.9\% of contribution to the project should go through the {\em Pull Request - Review - Revise - Merge process}. ``\href{https://ben.balter.com/2014/11/06/rules-of-communicating-at-github/}{There’s only one way to change something}'', Pull Request. A pull request should have a single purpose. If you have many purposes, then create many branches and make many pull requests. Why? Easier to refer to a small item, and easier to review a small item. Example of multiple purposes in a single pull request: \href{https://github.com/lanlab-org/LRR/pull/21/}{Allowing all group member to submit assignment and allowing Lecturer to edit assignments} \href{https://github.com/lanlab-org/GeneExpressionScatterPlot-Yu-Ye/pull/4}{Update README.md, change user guidance, fix csv exporting display probelm} You should wait other people to review your changes before you merge them to the master branch. Exceptions: the changes are trivial, the changes are unlikely to break the build, or no review for more than one week. Use pull request to communicate ideas. Use pull request to learn the code base. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Essential Git Commands} git branch git checkout -b FIX-README git add . git commit -m "README.md: Why, What, How?" git pull origin master git push origin FIX-README git checkout FIX-README %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Announcing} Show your \underline{presentable} work to the world. Put the announcement on the project home page. Post the announcement in the appropriate forums. One post per forum. General forum: https://news.ycombinator.com/ https://www.reddit.com/r/ subdirectories: opensource, programming, software. Topic-specific forums: mailing lists, web forums. Register at: \href{https://freshcode.club/}{fresh(code)}, \href{http://openhub.net/}{Black Duck Open Hub}. Make sure your announcement contain keywords that would help search engines find your project. Your announcement should be short and to the point. {\tiny \begin{verbatim} To: discuss@some.forum.about.search.indexers Subject: [ANN] Scanley, a new full-text indexer project. Reply-to: dev@scanley.org This is a one-time post to announce the creation of the Scanley project, an open source full-text indexer and search engine with a rich API, for use by programmers in providing search services for large collections of text files. Scanley is now running code, is under active development, and is looking for both developers and testers. Home page: http://www.scanley.org/ Features: - Searches plain text, HTML, and XML - Word or phrase searching - (planned) Fuzzy matching - (planned) Incremental updating of indexes - (planned) Indexing of remote web sites - (planned) Long-distance mind-reading Requirements: - Python 3.2 or higher - SQLite 3.8.1 or higher For more information, please come find us at scanley.org! Thank you, -J. Random \end{verbatim} } Running code provides the best foundation for success. Without running code? It may also work. Subversion (a design document, core developers). But there has to be something {\bf concrete/tangible} than just good intentions. You can announce after you made the project open-source. What you should expect: - {\bf No big impact}. Keep 1.0 quiet. - Some casual inquires. - A few more people in your mailing list. Announcing is seeding. Form exponential communications networks. Project $\rightarrow$ Community. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{More Comments than Code} Not only code comments. But also Pull Request Comments. % https://ben.balter.com/2017/05/23/seven-ways-to-consistently-ship-great-features/ {\small \begin{verbatim} Software Code Comment Code/Comment --------------------------------------------------------- GNU Nano 17718 3773 4.7 Git 474195 63652 7.4 Ubuntu 600750 120283 5.0 Apache HTTP Server 1512918 160160 9.4 MySQL 8631127 2754165 3.1 OpenStack 12951523 3146489 4.1 Android 16218632 4849352 3.3 Firefox 20684598 4528549 4.6 Linux Kernel 36680915 6701533 5.5 KDE 58707319 14434617 4.1 December 2019 Data Source: OpenHub https://www.openhub.net/ Copyright (C) 2020 Lan Hui \end{verbatim} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Version (revision) Control System} The core of version control is \underline{change management}: who made which change on which date. Two models: \begin{enumerate} \item Lock-Modify-Unlock \item Copy-Modify-Merge \end{enumerate} {\bf commit} - make change to the project. "I just committed a fix for the server crash bug people have been reporting on Mac OS X. Jay, could you please review the commit and check that I'm not misusing the allocator there?" {\bf push} - publish a commit to a publicly online repository. {\bf pull} (or update) - pull others' changes (commits) into your copy of the project. {\bf commit message} or log message - commentary attached to each commit, describing the nature and purpose of the commit. {\bf repository} - a database in which changes are stored and from which they are published. {\bf clone} - obtain one's own development repository by making a copy of the project's central repository. My fork. {\bf checkout} - switch to a branch {\bf revision or commit} - "Oh yes, she fixed that in revision 10" or "She fixed that in commit fa458b1fac". {\bf diff} - textual representation of a change. {\bf tag or snapshot} - Release\_1\_0, Delivery\_20130630. {\bf branch} - a copy of the project, under version control but isolated so that changes made to the branch don't affect other branches of the project. A great way to have multiple, independent lines of development. ``main line'', ``trunk'', ``master'', ``release branch''. {\bf merge} - move a change from one branch to another. {\bf conflict} - when two people try to make different changes to the same place in the code. ``resolve'' the conflict. {\bf revert} - undo an already-committed change to the software. What files should be put under version control? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Choosing a version control system} Git and Github. % https://ben.balter.com/2014/11/06/rules-of-communicating-at-github/ https://www.mercurial-scm.org https://subversion.apache.org %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Version everything} Any piece of information worth writing down is worth versioning \underline{in one place}. Source code, web pages, documentation, FAQ, design notes. Don't keep \underline{programmatically generated files} under version control. Things that don't change should be archived. For example, emails. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Refactoring Old Code and Building Upon It} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Losing Focus} Don't even think about creating bloatware, or groupware. Carry on your product vision. Many Distractions, One True North. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Rhythm of Releases} Successful software releases new versions regularly, e.g., \href{https://wiki.ubuntu.com/Releases}{Ubuntu}. To do that, the developers must have a release plan. Users know people behind the software are still improving it. Therefore, they feel more secure while using the software to do their business. A new release is like a booster shot to boost users' interest. Make sure you give people at least one Big booster shot yearly. However, too-frequent releases are considered not necessary for mature products. Why? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Joel Test} Answer the following 12 questions to measure how good a software team is. \begin{itemize} \item Do you use source control? \item Can you make a build in one step? \item Do you make daily builds? \item Do you have a bug database? \item Do you fix bugs before writing new code? \item Do you have an up-to-date schedule? \item Do you have a spec? \item Do programmers have quiet working conditions? \item Do you use the best tools money can buy? \item Do you have testers? \item Do new candidates write code during their interview? \item Do you do hallway usability testing? \end{itemize} Microsoft scores at 12. Most companies, 2-3. % https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-steps-to-better-code/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Managers} Management styles: \begin{itemize} \item Command-and-Conquer model. Cogs do the job. Charge on a minefield when caught in an ambush. \item Servant model. Creating \href{https://www.joelonsoftware.com/2006/04/11/the-development-abstraction-layer-2/}{Abstraction layer for Programmers} (first priority). \item Eco 101 model. Cash reward subverts instrinsic motivation. \item Identity model. Virtuous goal. Explain why we do this, but not that. \end{itemize} ``If a programmer somewhere is worrying about a broken chair, or waiting on hold with Dell to order a new computer, the abstraction has sprung a leak.'' - Joel Spolsky. Convert code into products below the decks. Quiet private office, a great computer, unlimited beverages, a comfortable ambient temperature. Roman army: 4 servants for every soldier. Modern army: 7:1. ``Even minor frustrations caused by using under-powered tools add up, making programmers grumpy and unhappy. And a grumpy programmer is an unproductive programmer.'' - Joel Spolsky. Dolly Parton. Bad management: \href{https://www.joelonsoftware.com/2006/08/09/the-econ-101-management-method/}{Econ 101 management}. ``Management simply doesn’t know how to teach people to do better work, so they force everybody in the system to come up with their own way of doing it.'' In the Zone. A good manager is a good listener. A good manager is involved. A good manager participates himself. A good manager cares about the quality of the project. A good manager never rewards unsatisfactory behavior. A good manager is a role model. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Micromanagement} Cannot {\em scale}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Customers} ``Customers Don’t Know What They Want. Stop Expecting Customers to Know What They Want.'' - Joel Spolsky. Iceberg Secret. They want to see pretty pixels. All about pixels. Psychology: making people feel better. % ``Use scrawls for the icons on the toolbar until the functionality is there.'' - Joel Spolsky. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Testers} {\bf Any big program has bugs}. QA department. Testers are your software's first users. The point is to get feedback. Programmers need immediate feedback from testers, positive or negative. 2:1. A dialogue, not a monologue. Payback. Positive reinforcement. Apply for a tester job, even if you don't know how to write program. Pick up a good book on testing. Learn automated test suites. Not only test whether a program works or not, but also check things like text fonts, colors, user interfaces. Misconception: let the worst programmer do the job (testing). Consequence: an incompetent team consistently producing poor products. \href{http://catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html}{Debugging is parallelizable}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Don't Want to Hire Testers} Microsoft hires many. Some companies do not believe in testing. \href{https://www.joelonsoftware.com/2000/04/30/top-five-wrong-reasons-you-dont-have-testers/}{Reasons}: \begin{itemize} \item I can’t afford testers! \item My customers will test the software for me. \item Bugs come from lazy programmers. \item My software is on the web. I can fix bugs in a second. \item Anybody qualified to be a good tester doesn’t want to work as a tester. \end{itemize} Need one tester for two programmers. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Employees} Two kinds of employees divided by their primary purposes: Make the company successful. Make themselves successful. Employ only one employee for a consistent architecture at early days. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Knowledge Workers} Need absolute concentraction. Quiet and private space - documented productiviity gain. Flow. Get into ``{\bf the zone}''. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Morale} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Software demo} Software demo is a marketing effort for ``\href{https://www.joelonsoftware.com/2002/02/13/the-iceberg-secret-revealed/}{speculative}'' software. Image matters most. Best venue in town. Dress slightly better than audience. Right room size. Play good music while people are waiting. Make everything as big as possible. Serve coffee. Tell a story. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Productivity} Fire and Motion. Launch the editor. Move forward a bit, every day. ``Many of my days go like this: (1) get into work (2) check email, read the web, etc. (3) decide that I might as well have lunch before getting to work (4) get back from lunch (5) check email, read the web, etc. (6) finally decide that I’ve got to get started (7) check email, read the web, etc. (8) decide again that I really have to get started (9) launch the damn editor and (10) write code nonstop until I don’t realize that it’s already 7:30 pm.'' - Joel Spolsky. ``Everyday our software is better and better.'' - Joel Spolsky. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Metcalfe’s Law} The value of a network grows by the square of the size of the network. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Delphi Effect} The ensemble method. The averaged opinion of a mass of equally expert observers is quite a bit more reliable a predictor than the opinion of a single randomly-chosen one of the observers. Variations in experts is important. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Lock-in} Unable / unwilling to switch. Stealth lock-in. Free for the first three months. Phone number. Word processor. Customer acquisition. %A record of the past activities for future reference. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The nature of software engineering} %% %% {\em Software is hard. -- Jamie Zawinski} %% %% \begin{itemize} %% %% \item Complex %% %% \item Iterative %% %% \item Creative and cooperative %% %% \item Changing technology %% %% \end{itemize} %% %% Common problems in software industry: unrealistic %% %% requirements/expectations, vague specifications, poor staff %% %% management, and ignoring user feedback. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{Triple constraints for software projects} %% %% Time, Cost and Quality. %% %% {\em Defer the activity of detecting and correcting software problems %% %% until late in the project, i.e., in the “test and validation” phase %% %% after the code has been developed. There are two main reasons why %% %% this is a mistake: (1) Most of the errors have already been made %% %% before coding begins; and (2) The later an error is detected and %% %% corrected, the more expensive it becomes. - Barry W. Boehm} %% %% The following figure shows ``increase in cost to fix or change software %% %% throughout life cycle''. %% %% \begin{center} %% %% \includegraphics[width=0.80\textwidth]{fig/BoehmCurve_real} %% %% \end{center} %% %% {\bf Important lesson: the longer you wait to detect and correct an error, the more it costs you - by a long shot.} %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{Aspects of management} %% %% Organisational policy management. Specific organisation-wide procedures for designing, implementing, estimating, tracking and reporting. Beneficial in the long-term. %% %% Personnel management. Specific organisation-wide procedures for hiring, training, motivating and promoting people. %% %% Communication management. %% %% Portfolio management. Having an overall vision not only of the software under development, but also of the software already in use in an organisation. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{Elements of project management} %% %% People, Product, Process, Project. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The people} %% %% The \underline{people factor} is the most important factor in SPM. Anyhow, we need right people to do the right thing. %% %% The manager who forgets that SE work is an {\em intensely human endeavor} will never success in project management. %% %% \newpage %% %% VP1: I guess if you had to pick one thing out that is most important to our environment, I'd say it is not the tools that we use; it is \underline{the people}. %% %% VP2: The most important ingredient that to be success on this project was having \underline{smart people}...very little else matters in my opinion. %% %% VP3: The only rule I have in management is to ensure I have \underline{good people} -- real, good people -- and that I grow good people -- and that I provide an environment in which good people can produce. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{People Capability Maturity Model} %% %% Capability Maturity Model Integration. %% %% A maturity model describes maturity level of an organisation. %% %% Originally called SEI, now called CMMI Institute. CMU (now acquired by ISACA), adopted and funded by U.S. DoD. %% %% Generic, not just for software engineering. %% %% For organisations, for organisations seeking to improve their process, for appraising/evaluating an organisation's maturity level (1-5). %% %% For people, PCMM is an integrated set of best practices that improves performance and key capabilities for organizations that want to improve their critical people management processes. %% %% \begin{center} %% %% \includegraphics[width=0.95\textwidth]{fig/PCMM} %% %% \end{center} %% %% \begin{center} %% %% \includegraphics[width=0.95\textwidth]{fig/P-CMM} %% %% \end{center} %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The product} %% %% Define product \underline{objectives} and \underline{scope}. Consider alternative solutions. %% %% Objectives: overall goals for the product (from the customer's point of view) without considering how these goals will be achieved. %% %% Scope: primary data, functions, behaviours that charaterises and bounds these characteristics in a quantitative manner. %% %% Alternatives: do we have better alternatives, considering the constraints on delivery deadline, budgets, personnel availability, etc. %% %% %Talk about OMG's SRS. %% %% %SE\_UserRequirementsDocument. %% %% %{\tiny https://lumos-hello.readthedocs-hosted.com/en/latest/} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The process} Use new and existing processes to move a project forward to success. Waterfall \begin{center} \includegraphics[width=0.80\textwidth]{fig/waterfall_marsic} \end{center} Prototyping The spiral model (Boehm) Agile (popular nowadays) \begin{center} \includegraphics[width=0.80\textwidth]{fig/ExtremeProgramming} \end{center} Scrum (seems really widely used nowadays). %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The project} %% %% Projects: 26\% failed, 46\% experienced cost and schedule overruns. %% %% We have to conduct {\em planned} and {\em controlled} software projects. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{PMBOK} %% %% Project Management Body of Knowledge includes the following KAs (knowledge areas): %% %% project integration %% %% project scope %% %% project time %% %% project cost %% %% project quality %% %% project human resource %% %% project communication %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{SWBOK} %% %% A closely related body of knowledge (Software Engineering Body of Knowledge). %% %% \begin{center} %% %% \includegraphics[width=0.50\textwidth]{fig/swebok_wiki} %% %% \end{center} %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{Measurement and management} %% %% Management without measurement suggests a lack of rigor. %% %% Measurement without management suggests a lack of purpose or context. %% %% Management and measurement without \underline{expert knowledge} is equally ineffectual. %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The top 5 factors found in successful projects} %% %% %{\tiny \texttt{http://www.umsl.edu/_titlt_sauterv/analysis/6840_f03_papers/frese/}} %% %% \begin{itemize} %% %% \item \underline{User Involvement} %% %% \item Executive Management Support %% %% \item Clear Statement of Requirements %% %% \item Proper Planning %% %% \item Realistic Expectations %% %% \end{itemize} %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{The top 5 indicators found in challenged projects} %% %% \begin{itemize} %% %% \item Lack of \underline{User Input} %% %% \item Incomplete Requirements \& Specifications %% %% \item Changing Requirements \& Specifications %% %% \item Lack of Executive Support %% %% \item Technical Incompetence %% %% \end{itemize} %% %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% \foilhead{All the top factors found in {\em failed} projects} %% %% \begin{itemize} %% %% \item Incomplete Requirements %% %% \item Lack of \underline{user involvement} %% %% \item Lack of Resources %% %% \item Unrealistic Expectations %% %% \item Lake of Executive Support %% %% \item Changing Requirements \& Specifications %% %% \item Lack of Planning %% %% \item Didn't Need it Any Longer %% %% \item Lack of IT management %% %% \item Technical Illiteracy %% %% \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Effort and Reward} When \underline{effort} and \underline{reward} do not correlate reliably, most people will lose faith and stop investing effort. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Form and Substance} Non-technical management. Language of customers (pretty pixels) versus language of programmers (data structure and algorithms). You should {\em look} prepared. Appearances matter. Iceberg Secret: 90\% underwater is programming work. 10\% which customers can see is user interface work. \href{https://www.joelonsoftware.com/2002/02/13/the-iceberg-secret-revealed/}{People Who Aren’t Programmers Do Not Understand This}. Form is substance. E.g., project presentation gives people an {\em immediate first impression}. Joel Spolsky's Corollaries: \begin{itemize} \item If you show a nonprogrammer a screen which has a user interface that is 90\% worse, they will think that the program is 90\% worse. \item If you show a nonprogrammer a screen which has a user interface which is 100\% beautiful, they will think the program is almost done. \item When you’re showing off, the only thing that matters is the screen shot. Make it 100\% beautiful. \end{itemize} Project home page is the first thing (probably also the last thing) a visitor learns about a project. Text editor project home pages: \begin{itemize} \item nano: https://www.nano-editor.org/ \item vim: https://www.vim.org/ \item emacs: https://www.gnu.org/software/emacs/ \item notepad++: https://notepad-plus-plus.org/ \end{itemize} How would you describe each's look and feel? Convey this message: ``your time will not be wasted if you get involved.'' One most important principle to make a project home page: people should have a rough idea where a link goes before clicking on it. Supply information, also supply comfort. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Canned hosting} Github Bitbucket Launchpad Savannah %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Looking for Existing Solutions First} Maybe not worthwhile to {\em reinvent the wheel}. Instead, add some functionality to the existing ones. Exceptions: for educational purposes, for very specialised applications, for national security. Places to look at: Search engines. Bing, Google, Baidu, etc. https://github.com https://freshcode.club https://openhub.net https://directory.fsf.org If you cannot beat it, join it. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Starting from What You Have} Transforming a private vision into a public one. What is obvious to you is not obvious to the world. Help visitors understand your project. Lower hacktivation energy. What your project is and is not? Strengths (for attacting people) and limitations (for setting expectation). Dependencies and assumptions. Write a mission statement, a README. Rearrange the code tree so that it conforms to widely accepted standards. Document the fundamental architectural assumption. Code tree: src/, bin/, lib/, etc/, include/, test/, share/, data/, example/, doc/, README, LICENSE, COPYING, MANUAL, TUTORIAL, FAQ, ... \href{https://github.com/github/choosealicense.com}{Choose a license}. Drudgery and no immediate benefit. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Continuous Improvement} While developing a software application is important, improving it is more important. \href{https://www.joelonsoftware.com/2001/07/21/good-software-takes-ten-years-get-used-to-it/}{10-year Rule}. It is hard to develop a software application, and {\em even harder} to continuously improve it, partly because people like new things and partly because people don't have enough motivation to read and maintain old code. \href{https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/}{It’s harder to read code than to write it}. Your software application becomes dead in the day when you stop improving it. You software application turns alive soon after you start improving it. \href{https://savannah.gnu.org/users/bens}{Benno Schulenberg} \href{https://git.savannah.gnu.org/cgit/nano.git/log/}{maintians} the Nano text editor. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{No Need to Provide Everything At Once} Don't let tasks overwhelm you. It would be prohibitively time-consuming to do the following: \begin{itemize} \item A thorough design document \item A complete user manual \item Beautifully and portably packaged code \item Platform independent \end{itemize} Provide the basics that can help newcomers to overcome initial obstacle of unfamiliarity. \underline{Hacktivation energy}: the amount of energy a newcomer must put in before he starts getting something back. You should make efforts to lower this energy threshold. \underline{Friction}: energy that a potential contributor needs to become a real contributor. % https://ben.balter.com/2013/08/11/friction/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Starting a New Project} {\bf Choose a good name}. A bad name can slow down adoption of the project. Good names: Project Apollo, Manhattan Project, Gutenberg Project, GNU Project, Gnome Project. Unique. Easy to remember. Not infringing on any trademarks. Spread your project's name. Own your project's name in as many of the relevant namespaces, e.g., twitter, IRC channels, github, weibo, ... The same project name should be available at as many places on the Internet as possible. Why? People can easily find you and check how your project is doing. \begin{itemize} \item Internet domain name (a simple URL). For example, https://www.gnome.org \item Twitter handle \item Username at github \item Account name at a microblog site (e.g., weibo.com) \item \href{http://lanlab.org/course/2020s/spm/irc-instruction.txt}{IRC} (Internet Relay Chat). Example: \#spm at irc.freenode.org. \end{itemize} {\bf Have a clear mission statement}. Concrete, limiting and {\em short}. Should target at specific audience. Should be prominently placed on the front page. For example, Hadoop (a distributed computing software which is able sort 1TB data on 910 nodes in less than 4 minutes). https://hadoop.apache.org/ \newpage {\scriptsize \begin{verbatim} The Apache™ Hadoop® project develops open-source software for reliable, scalable, distributed computing. The Apache Hadoop software library is a framework that allows for the distributed processing of large data sets across clusters of computers using simple programming models. It is designed to scale up from single servers to thousands of machines, each offering local computation and storage. Rather than rely on hardware to deliver high-availability, the library itself is designed to detect and handle failures at the application layer, so delivering a highly-available service on top of a cluster of computers, each of which may be prone to failures. \end{verbatim} } Your mission statement is mainly aimed at people with some knowledge about the related technique. Familiar with terms like ``cluster'' and ``high-availability''. {\bf State that the project is free}. The front page must make it \underline{unambiguously} clear that the project is open source. State that project is ``free and open-source'' and give an example license. Many people forget to do that. In extreme cases, the license was not given anywhere on the project's site at all — the only way to find it was to download the software and look at the license file inside the package. {\tiny \begin{verbatim} Inkscape license ================ Most of Inkscape source code is available under the GNU General Public License, version 2 or later, with the exception of a few files copied from GIMP, which are available under GNU GPL version 3 or later. As such, the complete binaries of Inkscape are currently covered by the terms of GNU GPL version 3 or later. Several standalone libraries contained in Inkscape's source code repository are available under GNU Lesser General Public License or the Mozilla Public License. See the files GPL2.txt and GPL3.txt for the full license text. \end{verbatim} } {\bf Demos, screenshots, videos, and example output}. Show that the software works. Prepare a short video (less than 4 minutes) and {\em say} this video is short. {\bf Features and requirements list}. If not completed yet, put ``planned'' or ``in progress''. {\tiny \begin{verbatim} MISSION STATEMENT To create a full-text indexer and search engine with a rich API, for use by programmers in providing search services for large collections of text files. FEATURES Searches plain text, HTML, and XML Word or phrase searching (planned) Fuzzy matching (planned) Incremental updating of indexes (planned) Indexing of remote web sites REQUIREMENTS Python 3.2 or higher Enough disk space to hold the indexes (approximately 2x original data size) \end{verbatim} } {\bf Development status}. How is the project doing? Promise versus reality. Are the people there, getting things done? {\em How active} is the project developed or maintained? How active is the community. Show News, near-term goals and needs, past releases (with feature lists), timeline of recent releases, bug tracker, discussion forum, and mailing list. Examples: \url{https://launchpad.net/drizzle}, \url{https://launchpad.net/inkscape}, \url{https://launchpad.net/schooltool}. Release notes: \url{http://wiki.inkscape.org/wiki/index.php/Release\_notes} {\bf Development status should always reflect reality}. Conservativism pays off in the long run; it's always better for the software to be more stable than the user expected than less. Alpha - first release, with known bugs. Beta - serious known bugs fixed, asking users for detailed feedback. Production. {\em 10-year Rule}. \href{https://www.joelonsoftware.com/2001/07/21/good-software-takes-ten-years-get-used-to-it/}{Good Software Takes Ten Years. Get Used To it}. Sustained effort is needed. Lotus Notes. 5 years' work before 1.0, released in 1989. From first line of code in 1984, to 10m users in 1995, 11 years have passed. Oracle DB (1977). Microsoft Word 1.0 (1983). All selling billions of dollars yearly. QQ (1998). \underline{Lessons}: (i) it takes many years before your software is good enough and serious enough for people to buy it. The Overhype syndrome. (ii) No time to add many wanted features to 1.0 in a short period of time. The Get Big Fast syndrome. (iii) When it is done, it is {\em done}. Additional features are not essential. (iv) ``We’ll Ship It When It’s Ready'' syndrome. Keep 1.0 quiet. We are not writing software any faster than before. We just release more often. {\bf Downloads}. Downloadable as source code. Conforming to standard build and installation methods. Otherwise, someone visits a web site, downloads the software, tries to build it, fails, gives up and goes away. {\bf Version control and bug tracker access}. You need a version control repository (e.g., a repo at GitHub, a repo at savannah, a repo on your own server). \begin{itemize} \item Create an account at GitHub. New an empty repo there. \item Clone that empty repo to your local machine. \\ \texttt{git clone https://github.com/account/repo.git}. \item Inside Git Bash, change directory to that local repo. \item After you have added files into that repo, issue the following commands, \texttt{git add .}, \texttt{git commit -m 'message'}, \texttt{git push origin}. \end{itemize} We also need a bug tracker (visible from the homepage of the project). For example, Bugzilla (started in 1998). Anyone tried \href{http://www.fogbugz.com/}{FogBugz}? The {\em higher} the number of bugs in the database, the {\em better} the project looks. It \href{https://www.rants.org/2010/01/bugs-users-and-tech-debt/}{indicates} the size of user pool and the convenience for reporting bugs. Things to avoid: (1) no bug database, (2) a nearly empty bug database. Example: \url{https://git.launchpad.net/inkscape/diff/src/extension/effect.cpp?id=53578d5ced44808d695e0495d244603a63e6292a} Example: a not initialized variable can cause problems in a new CPU architecture (ARM v7). \url{http://git.savannah.gnu.org/cgit/nano.git/commit/?id=7ad232d71470cd8c4dc63aeb02f11c9e8df9ecdb&h=master} {\tiny \begin{verbatim} author Devin Hussey 2019-03-28 17:28:47 -0400 committer Benno Schulenberg 2019-03-31 12:57:27 +0200 commit 7ad232d71470cd8c4dc63aeb02f11c9e8df9ecdb (patch) tree 95aaa66bc0269c68e4ba805821f8883db5ae93ce parent 85804ec70db060c21df48d5c2861cc39511559de (diff) download nano-7ad232d71470cd8c4dc63aeb02f11c9e8df9ecdb.tar.gz files: initialize a variable before referencing it The lack of initialization caused a nasty bug on some targets (such as ARMv7) which would make it so that ^S would just say "Cancelled". While x86 (both 64 and 32 bits) seems to initialize 'response' to zero or a positive number, ARM does not, and there is usually a negative value in its place, which triggers the 'if (response < 0)' check and, as a result, the code says "Cancelled". This fixes https://savannah.gnu.org/bugs/?56023. Reported-by: Devin Hussey Bug existed since version 4.0, commit 0f9d60a3. Signed-off-by: Devin Hussey Diffstat -rw-r--r-- src/files.c 2 1 files changed, 1 insertions, 1 deletions diff --git a/src/files.c b/src/files.c index 84e3f68..fd54c16 100644 --- a/src/files.c +++ b/src/files.c @@ -2101,7 +2101,7 @@ int do_writeout(bool exiting, bool withprompt) while (TRUE) { const char *msg; - int response, choice; + int response = 0, choice = 0; functionptrtype func; #ifndef NANO_TINY const char *formatstr, *backupstr; \end{verbatim} } {\bf Communications channels}. IRC is good. Try \href{http://lanlab.org/course/2020s/spm/irc-instruction.txt}{IRC}. However, it turns out that IRC in China is not at all popular. Everyone uses QQ or WeChat, intermixing their work with their life. Your presence on the list/forum does not imply a commitment to answer all questions or implement all feature requests. {\bf Developer guidelines}. For potential contributors. Basic elements: \begin{itemize} \item Pointers to forums. \item Instructions on how to report bugs and submit patches. \item Some indication of how development is usually done and how decisions are made — is the project a benevolent dictatorship (veto power), a democracy, or something else. \end{itemize} Good examples: \begin{itemize} \item \href{https://wiki.documentfoundation.org/Development}{LibreOffice} \item \href{https://subversion.apache.org/docs/community-guide/}{Apache Subversion} \item \href{https://www.apache.org/foundation/how-it-works.html}{Apache Foundation - How it Works} \item \href{https://www.apache.org/foundation/voting.html}{Apache Foundation - Voting} \end{itemize} Contrast Developer Guidelines with Developer Documentation. {\bf Developer documentation}. Developer guidelines tell programmers how to get along with each other; developer documentation tells them how to get along with the code itself. Wikis (need to be actively maintained.) {\bf Documentation.} Essential. People need something to read about your project. Make people's lives easier. Maintain FAQs (both online and in the distribution). Provide an all-in-one page so that people can search. Fine to be rudimentary and incomplete at first. The most important documentation for initial users is the basics: how to quickly set up the software, an overview of how it works, perhaps some guides to doing common tasks (tutorial). Plain text, HTML, Markdown, {\em reStructuredText}, \href{https://readthedocs.org}{Read The Docs} (an online documentation tool). Tell the readers the {\bf known deficiencies}, issues. {\bf Put everything in one page}. See things from the reader's point of view (hard). {\bf Hosting}. A website for users and a website for developers (code repo, bug tracker, development wiki, mailing lists, etc). Two sites link to each other. Not necessary in the beginning. Use canned hosting instead. {\bf Choosing a license and applying it}. What is a license? A student's answer: it provides protection to my project. Formal definition: a permit from an authority to own or use something, or do a particular thing. Free software license (``FSF-approved''), open source license (``OSI-approved''). The GNU General Public License (GPL v3). Two kinds of open-source licenses: FSF-approved, OSI-approved. There is a big overlap between the two. The ``Do Anything'' licenses: MIT-style. Assert nominal copyright and no warranty. Forbid proprietary programs to use my code: GPL (the GNU General Public License). GNU Affero GPL. With one extra clause in addition to GPL. For code running in cloud. How to apply a license? 1. State the license clearly on the project's front page. 2. Include the license in file LICENSE or COPYING in the software distribution itself. 3. Include a short notice at the top of each software source file. {\tiny \begin{verbatim} Copyright (C) <2008, 2009, 2013> # https://www.gnu.org/philosophy/free-sw.html The freedom to run the program as you wish, for any purpose (freedom 0). The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this. The freedom to redistribute copies so you can help others (freedom 2). The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this. \end{verbatim} } {\em Copyleft}. A copyleft license says that the derivative works must grant freedoms described in the parent license. Example: GPL, Affero GPL. {\em Permissive}. Does not require copyleft (non-copyleft). Example: MIT Licenses, Apache Software License version 2, and BSD license. License compatibility. Is license A compatible with license B? Make sure every contributor to the project agrees with the license to be used by collecting Contributor License Agreement from them. % Developer Certificate of Origin (DCO) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Good Precedents} Setup a mailing list - Easy. Keep discussions on-topic and productive - Hard. Change of development processes. For example, you have to be more careful about your public image. Turnovers. New arrivals. Project stability depends on: \begin{itemize} \item Formal policies, written rules - less important. Example: \href{https://ubuntu.com/community/code-of-conduct}{Ubuntu Code of Conduct}, \href{https://askubuntu.com/conduct}{AskUbuntu Code of Conduct}. \item Collective wisdom developed over time. \item Intangible, ever-evolving agreements. \end{itemize} {\bf Build social norms}. Healthy turnover won't damage \underline{social norms} because we have regular {\em transmission effort}. Evidence: songs survive for centuries. \begin{itemize} \item {\em What child is this (1865)? Greensleeves} (the 16th-century folk tune). \item {\em Classic of Poetry} (China's Book of Songs from 1046–771 BC). \end{itemize} People instinctively look for \underline{social norms} when they first join a group. {\bf Avoid private discussions}. [BAD] A Secret circle of people make {\em all} the Big decisions. As slow and cumbersome as public discussion can be, it's almost always preferable in the long run. {\em If there's no reason for it to be private, it should be public.} Why? The discussion will help train and educate new developers. The discussion will train you in the art of explaining technical issues to people who are not as familiar with the software as you are. The discussion will form archives for future reference. Bait for smart people. %There are smart people out there to contribute. Massive review. Many ideas. Slow in the short term. Fast in the long term. {\bf Zero-tolerance policy toward rudeness}. It is unfortunately very easy, and all too typical, for constructive discussions to lapse into destructive flame wars. It's a short distance from calling someone's technical proposal stupid to calling the person himself stupid. ``We don't do things that way around here,'' but then move on to the main topic. Never, ever insist on an acknowledgment, whether public or private, from someone that they behaved inappropriately. Forget about it and move on. {\bf Codes of Conduct}. \href{https://askubuntu.com/conduct}{AskUbuntu Code of Conduct} \href{https://ubuntu.com/community/code-of-conduct}{Ubuntu Code of Conduct} \href{https://www.contributor-covenant.org/version/1/4/code-of-conduct}{Contributor Covenant} It it OK if someone thinks that a code of conduct is not necessary. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Write Everything Down} Writing is great. ``Reading text is better communication than having meetings.'' -- Zach Holman. In a distributed work environment, writing everything down is crucial for effective communication. Why? People cannot see your face, hear your sound, or read your gesture when you are not not in the same place. No problem. We could write. Writing is so powerful that we are still able to read people's thoughts after they are dead for centuries. For example, books written in 1810, 1859, etc. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Code review} Commit review. {\em Peer review} in the open source world. Benefits: \begin{itemize} \item Fostering a productive development community. \item Improving software quality. Catch bugs before they slip in. \end{itemize} Review other people's {\em fresh} code. Let other people review your {\em fresh} code. Review means making some timely comments. Ask stupid questions, and ask many. Do this regularly. Don't do this after six months. Look for bugs and areas of possible improvement. Thing we could catch: memory leaks, off-by-one errors, insufficient comments, insufficient API documentation, security vulnerabilities, compliments ... Example of insufficient comments: {\small \begin{verbatim} for item in A.iter(sentence): return True return False \end{verbatim} } {\bf Important} to have more eyeballs. Given enough eyeballs, all bugs are shallow. Given a large enough beta-tester and co-developer base, almost every problem will be characterized quickly and the fix obvious to someone. -- Eric Steven Raymond, \href{http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/}{The Cathedral and the Bazaar} Look at other people's code {\em changes as they arrive}. Why do we focus on reviewing recent changes? \begin{itemize} \item It works better socially. Timely feedback for fresh changes. A great way to interact with people. Confirm that what they do {\em matters} (is seen and understood). People do their best work when they know that others will take the time to evaluate it. \item The recent change is a good starter for getting familiar with the code base. Also look at the affected callers and callees. \end{itemize} Result - better software quality. The review should be public, so that other people can see it and know that a review has happened, and is expected. Commit Notifications are useful. {\tiny \begin{verbatim} Branch: refs/heads/master Home: https://github.com/SYHWY/project_one Commit: e6873456c6f525ac10633fa660da1b3e8e454394 https://github.com/SYHWY/project_one/commit/e6873456c6f525ac10633fa660da1b3e8e454394 Author: SYHWY <49365180+SYHWY@users.noreply.github.com> Date: 2019-05-04 (Sat, 04 May 2019) Changed paths: M service.py Log Message: ----------- add delete method add delete method for pages Branch: refs/heads/master Home: https://github.com/DragonDove/thoth Commit: 3f5c59c81926bccdfb021f6056f12b4b696e281e https://github.com/DragonDove/thoth/commit/3f5c59c81926bccdfb021f6056f12b4b696e281e Author: Dragon Dove <874898731@qq.com> Date: 2019-05-02 (Thu, 02 May 2019) Changed paths: M app.py M util.py Log Message: ----------- Remove unnecessary code, ignore the data in for loop Branch: refs/heads/master Home: https://github.com/DragonDove/thoth Commit: 9b76f235176f403201da3a08d5bcf7f1f01a7e76 https://github.com/DragonDove/thoth/commit/9b76f235176f403201da3a08d5bcf7f1f01a7e76 Author: Dragon Dove <874898731@qq.com> Date: 2019-05-02 (Thu, 02 May 2019) Changed paths: M templates/uploadPage.html M view.py Log Message: ----------- Fix issue, No subject is chosen when uploading \end{verbatim} } A valuable way to spend time. One could contribute as much to the project by reviewing others' changes as by writing new code. Case study. Greg Stein reviewed every line of every single commit that went into the code repository, and never complained about being the single reviewer. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Technical debt} Like financial debt. It is a debt, and you need to pay it off in the future (with interest). ``When taking {\em short cuts} and delivering code that is not quite right for the programming task of the moment, a development team incurs Technical Debt. This debt decreases productivity. This loss of productivity is the interest of the Technical Debt.'' High technical debt would make the software not maintainable. https://www.agilealliance.org/introduction-to-the-technical-debt-concept/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{FIXME} It is a good practice to insert the tag \texttt{FIXME} in your code that needs further attention. Why? Easy to grep and easy to search. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{README} Use this file to convey Why, What and How. Treat this file as the project's constitution. Use this file to avoid feature creep. %https://ben.balter.com/2017/04/14/your-projects-readme-is-your-project-constitution/ %https://opensource.guide/building-community/#treat-your-README-as-a-constitution %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Be open from day one} Being open and being closed will affect your ways in - handling sensitive/confidential data - wording in code comments - choosing dependencies Note: cleaning up needs extra time and decision-making. Also, you don't want all issues in your source code to expose suddenly to the public. ``In the open'' means the following things are accessible by the public in day 1: - The code repository - Bug tracker - Design documents - User documentation - Wiki - Developer discussion forums Your daily work is visible to the public. Compatible with being open source. \newpage ``In the open'' does NOT have to mean the following - allowing strangers to check code into your repository - allowing anyone to file bug reports in your tracker - reading and responding to every bug report filed, even if you do allow strangers to file - responding to every question people ask in the forums - reviewing every patch or suggestion posted, when doing so may cost valuable development time \underline{Your source code is open, but your time is not open.} Pace of engagement. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Opening a formerly closed project} Like exposing your underwear to the world. Mechanical difficulties you may encounter: Your code depends on proprietary, platform-dependent libraries. Confidential data (e.g., unpublishable comments, passwords or site-specific configuration information). Solutions: use open-source libraries, start from \underline{``top-skim''} version. Managerial issues (1) make sure everyone in the team understand that a BIG change is coming. (2) make sure that you understand how it's going to feel from their point of view. Put yourself in their shoes. - Embarrassment. Expose code to strangers. What if someone points out flaws in the code publicly. - Criticisms. Strangers don't know the developers so they can make {\bf bold} comments. But you cannot criticise them (faceless entities). - Strangers are not aware of business pressures forced on the developers. - Lots of questions from strangers suggest inadequate documentation. - Burden of external communications. Solution: - Don't worry. - The above discomfort is perfectly normal. - Will get better. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Why open source?} % https://ben.balter.com/2015/11/23/why-open-source/ How does it compare to open access. Paywall. Europe’s open-access drive escalates as university stand-offs spread. A key driver behind the activity in Europe is the European Commission’s goal that, by 2020, all research will be freely accessible as soon as it is published. \url{https://www.nature.com/articles/d41586-018-05191-0} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Technical infrastructure} Brooks' Law - adding manpower to a late software project makes it later. Communication complexity is proportional to $n^2$. We need good information management. But don't over-automate. The technical infrastructure gives humans easy ways to apply \underline{care}. Parliamentary procedure - (Mr. Speaker) keeps some people quiet while others are speaking. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{What a project needs} Web site - better to separate user-facing from developer-facing. Cross-linked. https://www.libreoffice.org/ Mailing lists / Message forums Version control % change porting??? Bug tracking Real-time chat %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Canned hosting} An online service that offers online collaboration tools needed to run a free software project. Tools: version control repo, bug tracker, wiki, mailing list. Advantages: (1) server capacity and bandwidth (2) simplicity. Disadvantages: limited customisation, no fine-grained control. If you are not sure you can do better, just use \underline{canned hosting}. GitHub - https://github.com \href{https://ben.balter.com/2014/11/06/rules-of-communicating-at-github/}{15 rules for communicating at GitHub} Pull Request, line-by-line commenting. Mailing lists: https://discourse.org, https://groups.google.com (*), http://groupserver.org/, mailman http://www.list.org (*), https://mail.python.org/mailman/listinfo/python-dev, https://mail.python.org/mailman/listinfo/flask Sympa https://www.sympa.org, dada http://dadamailproject.com For Mercurial users, check https://en.wikipedia.org/wiki/Comparison\_of\_open\_source\_software\_hosting\_facilities %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Open source hosting} Should the \underline{hosting itself} be open source? Fully open source infrastructure: \url{http://phabricator.org}, \url{https://gitlab.com} Redmine - a flexible project management web application ** As long as you can: - Interact with project data in automatable ways - Export the data It should be fine. Remember: running open-source hosting code in a production environment can be difficult. Why? Multiple servers, customised networks, dedicated staffs ... %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Anonymity and involvement} You don't want strangers to push changes into your repo, even they are reviewed. You don't want a inconvenient \underline{involvement bar} preventing quick comments and easy bug reporting. Make sure read-only actions, bug filing (with proper anti-spam techniques, such as captchas) are allowed for anonymous, non-logged-in visitors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Mailing lists / message forums} A small, focused project - the email gateway features of the bug tracker. Issue Ticket. A large, complex project - a dedicated discussion forum. Your project should have a \underline{prominently-placed} description of all the available public forums. See page 43 in the text book for an example. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Choosing the right forum management software} Both email- and web-based access. https://mail.vex.net/mailman/listinfo.cgi/alpine Moderation features. Rich administrative interface. E.g., handling obsolete email addresses. Header manipulation. {\tiny \begin{verbatim} From:... To: Subject: [Scanley Discuss] Making the 2.5 release Date:... Reply-to:... \end{verbatim} } Archiving. https://mail.python.org/pipermail/python-dev/ SPAM prevention. Purpose: (1) Avoid your list/forum to be occupied by spam posts. (2) Avoid your list/forum to be a source of email addresses for spam harvesters. Measures: (1) Only auto-allow postings from list subscribers. Non-subscribers' posts go to a moderation queue. (2) Filter posts through spam-detection software. SPMX. (3) Moderation. Mailing list moderation is strictly about keeping the list free of spam, and of wildly off-topic or otherwise inappropriate emails, nothing more. (4) Address-hiding in archives. jrandom@somedomain.com \\to jrandom\_AT\_somedomain.com \\or to jrandomNOSPAM@somedomain.com. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The great Reply-to debate} Reply-to: discuss@lists.example.org What if someone sends a confidential, private message to the author when the author sets Reply-to to the list address? Accidentally sending a private mail to a public list! % author, reply-to %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Archiving} Prompt updating (instantaneous, every hour) Referential stability (keep the same URL) Thread support Searchability %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Browsability} The project's repository should be browsable on the Web. Browsability is important because it is a lightweight portal to project data. Browsability also implies canonical URLs for viewing a particular change. % Skipped: Singularity of Information % Skipped: Authorization %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Commit notifications / commit emails} Every commit to the repository should generate a notification in a subscribable forum/mailing list. This notification is generated by the version control system. Who made the change, when they made it, what files and directories changed, and the actual content of the change. Include the diff, set ``Reply-to'' to the regular development list. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Bug Tracker} A bug tracker is more important and more useful that you might think. A first place to check a project's overall health. https://savannah.gnu.org/bugs/?53986 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=908678 A bug tracker can track non-bug information, e.g., new feature requests. The tracker is as much a public face of the project as the repository, mailing lists or web pages. Other names: issue trackers, \underline{ticket} trackers, defect trackers, artifact trackers, request trackers. Bug Triage. Reproduce the bug. Invalid bug reports and duplicate bug reports will increase the noise to signal ratio. Regression. Fixed then re-appear. Bug life cycle. Bug severity: blocker, critical, major, normal, minor, trivial, enhancement. Bug importance: highest, high, normal, low, lowest. Bug state: open, unverified, diagnosed, confirmed, assigned, in progress, resolved (fixed, invalid, wontfix, duplicate worksforme), closed. It takes considerable time for people to report a bug. Acknowledge each bug report with a timely response. Interact with email. Respect anonymity. How to keep the bug tracker free of junk? Buddy system: ``Did you search the bug tracker to see if it's already been reported?'' %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % wed start here \foilhead{Ticket life cycle} Someone files the ticket. We got an OPEN ticket. Others read the ticket, add comments to it, and perhaps ask the original filer for clarification on some points. The bug gets reproduced. The bug gets diagnosed. Assign ownership. Set priority. The ticket gets scheduled for resolution. The bug gets fixed. The ticket is CLOSED. Things to notice: not a genuine bug, a duplicate bug. % This centrality to the life of the project implies a few things about trackers' technical features %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Tracker's interaction with email} Create new tickets by email. Add new comments to a ticket by email. "Subscribe" to a ticket to receive relevant emails. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Pre-filtering the Bug Tracker} Duplicate or invalid tickets. Keep the tracker clean by a bug report watcher who \underline{watches} each incoming ticket. Buddying system. Get confirmation from another guy ({\em buddy}) first before filing the bug report. "Did you search the bug tracker to see if it's already been reported?" %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Internet Relay Chat} Or IRC for short. Real-time chat systems. Text-based. Many IRC channels running on an IRC server (e.g., irc.freenode.org). Channel topic. Use pastebins (paste sites) for large text or images. Bots. Commit notifications in IRC. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Wikis} https://www.dokuwiki.org/dokuwiki https://en.wikipedia.org/wiki/Comparison\_of\_wiki\_software Click and edit. Clear page organisation strategy. A common vision. Extensive guidance on how to write new entries. What to avoid. Dispute resolution process. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Q \& A forums} https://stackoverflow.com %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Social Networking} Presence on mainstream social media platform. @AskLibreOffice tweet stream. %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% \foilhead{Translation infrastructure} %% https://transifex.com %% https://translations.launchpad.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Social and Political Infrastructure} How does it work? What keeps the free software project running, on a day-to-day basis? How conflicts are resolved? Who makes the decisions? Success is \underline{not} only about technical success. Operational health: ongoing ability to incorporate new code contributions and new developers, and to be responsive to incoming bug reports. Survivability: ability to exist independently of any individual participant or sponsor. Governance structure and established procedures well followed by participants. %meritocracy??? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Fork and forkability} Take a copy of the source code and use it to start a competing project, known as a \underline{fork}. Result: no true dictators in free software projects. Bad decisions would eventually bring about a revolt and a fork. %by fiat, anointed the BD, leadership by a charismatic individual %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Benevolent dictators} One person makes the \underline{final} decisions. BD - community-approved arbitrator. For example, the founder of a project. Two things to note: (1) BD usually does not have enough expertise in all areas. (2) Quality developers won't stay if they could not influence the project's direction. In case of no consensus and most developers want to move on, a BD would say ``This is the way it's going to be.'' Traits of a good BD. (1) Self-restraint. No BD's personal opinions or conclusions in the early discussion so that everyone can speak. (2) Acknowledge his own bad decisions. (3) Does not need to have the sharpest technical skills. If the project has an obvious, good candidate BD, then that's the way to go. Otherwise, use democracy. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Consensus-based democracy} Group-based governance is more ``evolutionary stable''. If a group of N people were to give one person with special power, it would mean that N-1 people were each agreeing to decrease their individual influence. People usually don't want to do that. Discussion and voting (head count). Identify key issues. Do approval voting (each voter can vote for as many of the choices on the ballot). Consensus simply means an agreement that everyone is willing to live with. Software: https://vote.heliosvoting.org/. Guidelines: https://www.apache.org/foundation/voting.html Compromise or vote? Voting ends creative thinking to solve a problem. We should prevent a premature vote. ``I don't think we are ready for a vote yet''. Show hands. Offer a new solution, or a new viewpoint. Voters do not have to be coders (committers). People who did valuable contributions to the project can be voters, e.g., people who provide legal help, or organize events, or manage the bug tracker, or write documentation. The decision to add a new voter should be made secretly. Implicit consensus. Silence means consent. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Polls} Ask \underline{all} the subscribers of the project's mailing lists to vote, for example, on user interface choice. Make sure there is a write-in option (a better option not mentioned in the poll questions). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Vetos} A veto (-1) can halt a hasty or ill-considered change, at least long enough for everyone to discuss it more. Any veto should be accompanied by a thorough explanation. A veto can be overridden if there is a clear majority for moving on. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Consensus approval versus majority approval} Consensus approval: at least three binding +1 votes and no vetos. Majority approval: at least three binding +1 votes and more +1 votes than -1 votes. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Writing it all down} At some point, the number of conventions and agreements floating around in your project may become so great that you need to record it somewhere, linking to mailing list discussions. Don't try to be comprehensive. Base the document on the questions that newcomers ask most often, and on the complaints experienced developers make most often. Make it clear that the rules can be reconsidered. Project guidelines: https://wiki.documentfoundation.org/Development https://subversion.apache.org/docs/community-guide/ https://www.apache.org/foundation/how-it-works.html % erratum: said to % No punctuation before By the time %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Version control means you can relax} The change can be reverted. So we can undo the effects of bad or hasty judgment. But this does not mean we could abuse reversion. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Joining or creating a non-profit organization} Tax-exempt. 501(c)(3). Umbrella organizations. Software Freedom Conservancy https://sfconservancy.org/ ** Apache Software Foundation https://apache.org/ Organizational governance at the Apache Software Foundation has the following {\bf entities}: \begin{itemize} \item Board of Directors \item Project Management Committees \item Corporate Officers \end{itemize} https://www.apache.org/foundation/governance/orgchart %Eclipse Foundation https://eclipse.org/ %Software in the Public Interest http://spi-inc.org/ %Linux Foundation http://collabprojects.linuxfoundation.org/ The organization is there to handle things the developers don't want to handle. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The Apache Way} The name Apache came from {\em Native American Apache Nation}. The foundation's first software - HTTPD Web Server (1995-1999). Consensus-based, community driven governance. Project Management Committees have a high degree of freedom. Communication is done using mailing lists (asynchronously). Voice communication is extremely rare. Why? Decision-making: ``meritocracy'', ``do-ocracy'' power of those who do: the more you do the more you are allowed to do. Use lazy consensus (silence means no objection). +1, 0 (no opinion), -1 (need to provide an alternative proposal). Philosophy \begin{itemize} \item Collaborative software development \item Commercial-friendly standard license \item Consistently high quality software \item Respectful, honest, technical-based interaction \item Faithful implementation of standards \item Security as a mandatory feature \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{ASF Incubator} Entry point to become a ASF project. It filters projects on the basis of success likelihood. Requirements: a working codebase, the intention to assign sufficient intellectual property rights, and a sponsoring ASF member or officer. \url{http://apache.org/foundation/how-it-works.html#management} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Project Management Committees at the Apache Software Foundation} The Chair is appointed by the Board. Daniel Gruno. Apache HTTP Server. Mladen Turk. Apache Tomcat. Paul Angus. Apache CloudStack. Matei Zaharia. Apache Spark. Josh Thompson. Apache VCL (Virtual Computing Lab). Vinod Kumar Vavilapalli. Apache Hadoop. Peter Kovacs. Apache OpenOffice. \url{http://www.apache.org/foundation/} Hadoop PMC: \url{http://hadoop.apache.org/who.html} Manage their projects independently. Quite autonomous. Lead and oversee the project. Set per-project policies. Vote on product releases. Elect new PMC members. Main role is not code and not coding. ``Ensure balanced and wide scale peer review and collaboration.'' ``We worry about any community which centers around a few individuals who are working virtually uncontested.'' {\bf Committers} (elected based on merit) have write access to the project. PMC chairs report to the board quarterly about the health and status of their project. Communications. (1) private@list for discussing sensitive topics (e.g., personnel matters or inviting new committers). (2) dev@list for discussing about the future of the project. All project business is conducted on normal public mailing lists. \url{https://www.apache.org/foundation/governance/pmcs.html} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Mailing lists} ``The benefit of using mailing lists over private communication is that it is a shared resource where others can also learn from common mistakes and as a community we all grow together.'' \url{http://hadoop.apache.org/who.html} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Review-Then-Commit or Commit-Then-Review} RTC: change needs consensus approval first. CTR: make changes at will with the possibility of being retroactively vetoed. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Communications} Many things to do in a project: \begin{itemize} \item Recruit users and developers. \item Encourage new contributors to become more deeply involved. \item Allow free-flowing discussion while still reaching necessary decisions. \item Maintain a body of knowledge and convention that guides newcomers and experts alike. Hadoop web site - Development - How to contribute \item Produce working software. \end{itemize} The most important skill: \underline{writing clearly}. Programming skills or communication skills. What matters more? Is there any correlation between these two sets of skills? Without good communication skills, how do you convince others to support you? How do you coordinate people to accomplish a complex task. \underline{Keep your readers' background in mind} How much knowledge can you assume on the part of the reader when you post an answer in a mailing list? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{You are what you write} People may never see you in person. But they can guess about your personality through your writing. ``Your image on the Internet comes from what you write, or what others write about you.'' Is your writing lucid, informative? Is your writing disorganised, illogical? \underline{Structure and formatting.} Write in complete sentences, capitalizing the first word of each sentence, and use paragraph breaks where needed. Book to read: Strunk and White. The Elements of Style. \underline{Email}. Use plain text (not html). {\em Top-post} or quote the relevant portion of the original text first, followed by your response. Stay under 80 columns wide for quoted code or error messages. Write a informative, succinct subject line. \underline{Content}. Content is the King. Make things easy for your readers. Consider the {\em reader-to-writer ratio}. Don't exaggerate (it can hurt your credibility). {\tiny \begin{verbatim} Disagreement expression 1 ------------------------- Doing it that way would make the code totally unreadable. It'd be a maintenance nightmare, compared to J. Random's proposal... disagreement expression 2 ------------------------- That works, but it's less than ideal in terms of readability and maintainability, I think. J. Random's proposal avoids those problems because it... \end{verbatim} } {\bf Reread and edit}. What you read in articles, newspapers, and books have undergone {\em many} revisions. \underline{Tone}. Be terse. Terseness dose not mean coldness. Others' feelings matter: unhappy people write worse software. So we should be careful in choosing words. {\small \begin{verbatim} Can you possibly elaborate a bit more on exactly what problems you ran into, etc? Also: What version of Slash are you using? I couldn't tell from your original message. Exactly how did you build the apache/mod_perl source? Did you try the Apache 2.0 patch that was posted about on slashcode.com? Shane \end{verbatim} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Recognizing rudeness} \underline{What is {\bf not} rude?} Technical criticism. It indicates people are seriously interested in your work. Straight questions. ``Is your computer plugged in?'' \underline{What {\bf is} rude?} Failure to provide \underline{quality} criticism can be a kind of insult. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Face} Use a consistent {\em screen name} everywhere: email address, IRC, repository committer name. That name is your online ``face''. {\small \begin{verbatim} From: "Karl Fogel" \end{verbatim} } Henk Penning (\texttt{henkp}) and Vadim Gritsenko (\texttt{vgritsenko}) The real name is {\em real}. {\small \begin{verbatim} From: "Wonder Hacker" \end{verbatim} } A fantastical online identity never impresses readers. Maybe you're simply insecure. Use your real name for all interactions. Use brief signature blocks, or none. A counter example: page 122 in the textbook. % TBR: Avoiding Common Pitfalls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Common pitfalls} \underline{You have to respond to everything.} {\em Silence is also communication. If you don't know how to answer, answer using silence. - Hui} A response should have a definite purpose. Think twice before you post (1) what do I want to accomplish? (2) will it not get accomplished unless I say something? Respond when you see (1) flaws in a proposal (2) miscommunications. {\bf It's always better to leave people wishing you'd post more than wishing you'd post less.} \underline{Unproductive threads.} High noise/signal ratio. Bad tone. {\small \begin{verbatim} This discussion is going nowhere. Can we please drop this topic until someone has a patch to implement one of these proposals? There's no reason to keep going around and around saying the same things. Code speaks louder than words, folks. Several proposals have been floated in this thread, but none have had all the details fleshed out, at least not enough for an up-or-down vote. Yet we're also not saying anything new now; we're just reiterating what has been said before. So the best thing at this point would probably be for further posts to contain either a complete specification for the proposed behavior, or a patch. Then at least we'd have a definite action to take (i.e., get consensus on the specification, or apply and test the patch). \end{verbatim} } \underline{The smaller the topic, the longer the debate.} {\bf Bikeshed effect}: the amount of discussion is inversely proportional to the complexity of the topic. {\em Parkinson’s Law of Triviality} {\em Parkinson shows how you can go in to the board of directors and get approval for building a multi-million or even billion dollar atomic power plant, but if you want to build a bike shed you will be tangled up in endless discussions.} An atomic plant: so vast, so expensive, and so complicated that people cannot grasp. A bikeshed: everyone knows about it. No matter how reasonable you are with your proposal, somebody will seize the chance to show that he is doing his job, that he is paying attention, that he is here. \underline{The ``Noisy Minority'' effect}. The best way to counteract this effect is to point it out very clearly and provide supporting evidence showing how small the actual number of dissenters is, compared to those in agreement. \underline{Hawthorne effect}. \underline{Holy wars}. Find some way to express sympathy and understanding for the points the other side is making. \underline{Bash competing open source products}. Refrain from giving negative {\em opinions} about competing open source software. One reason: developers overlap. \underline{Difficult people}. E.g., a filibuster (obstructionist) who keeps claiming that the matter under discussion is not ready for resolution, and offers more and more possible solutions. Purpose behind: to make everyone else take him seriously. How to handle? Better just to tolerate it for a while. Remember: although the other person may be the one behaving destructively, you will be the one who appears destructive if you make a public charge that you can't back up. If you take action on him, collect examples/evidence first. \newpage A case study of an excessive poster. {\tiny \begin{verbatim} From: "Brian W. Fitzpatrick" To: [... recipient list omitted for anonymity ...] Subject: The Subversion Energy Sink Date: Wed, 12 Nov 2003 23:37:47 -0600 In the last 25 days, the top 6 posters to the svn [dev|users] list have been: 294 kfogel@collab.net 236 "C. Michael Pilato" 220 "J. Random" 176 Branko #ibej 130 Philip Martin 126 Ben Collins-Sussman I would say that five of these people are contributing to Subversion hitting 1.0 in the near future. I would also say that one of these people is consistently drawing time and energy from the other 5, not to mention the list as a whole, thus (albeit unintentionally) slowing the development of Subversion. I did not do a threaded analysis, but vgrepping my Subversion mail spool tells me that every mail from this person is responded to at least once by at least 2 of the other 5 people on the above list. I think some sort of radical intervention is necessary here, even if we do scare the aforementioned person away. Niceties and kindness have already proven to have no effect. dev@subversion is a mailing list to facilitate development of a version control system, not a group therapy session. -Fitz, attempting to wade through three days of svn mail that he let pile up \end{verbatim} } Developers who do not follow requirements. Acceptance Criteria. % https://pm.stackexchange.com/questions/27404/what-to-do-with-developers-who-dont-follow-requirements %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Handling growth} Mailing list (users@, help@, discuss@) - a few thousand users and/or a couple of hundred posts a day. Imagine Microsoft had a mailing list for Windows. Strategies: (1) divide into more specific topics. (2) organise information so that it can be easily found. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Conspicuous use of archives} All communications in an open source project are archived. Why are archives important? They provide a basis for discussion. Search the archive first before you ask a question. To avoid duplication, if a question has already been answered in the archive, refer to it (e.g., include a link to the archive page) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Treat all resources like archives} Project information should be at stable, conveniently searchable addresses. - Direct searchability - Availability to major Internet search engines - Browsability - Referential stability - Editability FAQ: (1) in an HTML page (2) a table of contents (3) name anchors for individual anchors (4) easy to edit and to version. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Codify tradition} Newcomers to a project face a bigger \underline{acculturation burden} because a huge body of \underline{tradition} has accumulated. Project norms such as coding standards, communications conventions, and other technical minutae. Watch for patterns in how people get confused and make a guideline. The guideline should be easily visible. Formatting of the guideline makes a big difference. http://subversion.apache.org/reporting-issues.html Use 'r12908' or 'revision 12980' to refer to a revision. 'r12980' is a better referral method. Consistency means that everywhere people look, they see the same patterns being followed, and start to follow those patterns themselves. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Choose the right forum} IRC or development mailing list? IRC: good for quick response, not good for making big decisions as the sample size is small. Mailing list: more formal. Every interested party will have an opportunity to see and respond to the relevant posts, regardless of time zones, schedules. Switch from the narrow forum (e.g., bug/ticket trackers) to a broader forum for forum appropriateness. Cross-link between the old forum and the new forum. Open source is fundamentally a \underline{writer-responsible} culture. Paste important summaries and/or conclusions from the list discussion back to the ticket. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Announcing releases and other major events} Where? Front page (brief synopsis), News or Press Releases (details) of your project's website. Twitter handles. RSS feeds. Forums. Mailing list (announce@yourprojectdomain.org). Make the announcements in all these places at the same time, as nearly as possible. For a less important event (e.g., next release date), use a daily mailing lists (not the announce list). {\tiny \begin{verbatim} Just a progress update: we're planning to release version 2.0 of Scanley in mid-August 2005. You can always check http://www.scanley.org/status.html for updates. The major new feature will be regular-expression searches. Other new features include: ... There will also be various bug fixes, including: ... \end{verbatim} } %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% \foilhead{Announcing security vulnerabilities} %% Basic guidelines: (1) Don't talk about the bug publicly until a fix is available; then supply the fix at the same time you an- %% nounce the bug. (2) Come up with that fix as fast as you can. %% \begin{itemize} %% \item Receive the report. A seperate mailing list or contact form for receiving security bug reports. Only ``trusted developers'' can read them. Make sure the submission is secure (encripted using https or GPG [Gnu Privacy Guard] or PGP [Pretty Good Privacy]). %% \item Develop the fix quietly. Evaluate severity and urgency. How serious is the vulnerability? How easy is it to exploit the vulnerability? Who reported the problem to you? A developer. \texttt{anonymous14@globalhackerz.net}. A security professional. What's the deadline for making the bug public (go-public date)? \underline{Do not commit the fix to any public repository.} %% % exam: if a security bug report comes from one of your team members, then you don't have to fix the bug promptly. %% \item CVE (Common Vulnerabilities and Exposures) numbers. "CVE-2014-0160". https://cve.mitre.org/cgi-bin/cvename.cgi?name=2014-0160 %% \end{itemize} %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% \foilhead{Common Vulnerability Scoring System} %% CVSS is developed by the \underline{National Vulnerability Database} at the U.S. National Institute of Standards (NIST). %% Assign a score to severity of vulnerability. %% https://nvd.nist.gov/ %% {\tiny %% \begin{verbatim} %% CVSS v2.0 Ratings CVSS v3.0 Ratings %% Severity Base Score Range Severity Base Score Range %% None 0.0 %% Low 0.0-3.9 Low 0.1-3.9 %% Medium 4.0-6.9 Medium 4.0-6.9 %% High 7.0-10.0 High 7.0-8.9 %% Critical 9.0-10.0 %% \end{verbatim} %% } %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% \foilhead{Pre-notification} %% Once a fix is ready, who should be notified first, average users or well-known online services? %% \underline{Pre-notification} simply means contacting those administrators privately before the go-public date, telling %% them of the vulnerability and how to fix it. %% The qualification for receiving pre-notification: (1) the recipient must run a large, important service where %% a compromise would be a serious matter. (2) the recipient must not leak the security problem before the go-public date. (3) Secure communication. %% If use email, send the pre-notification individually. What would happen if we send it to all recipients at once? %% \newpage %% {\tiny %% \begin{verbatim} %% From: Your Name Here %% To: admin@large-famous-server.com %% Reply-to: Your Name Here (not the security list's address) %% Subject: Confidential important notification. %% [[[ BEGIN ENCRYPTED AND DIGITALLY-SIGNED MAIL ]]] %% This email is a confidential pre-notification of a security alert %% in the Scanley server software. %% Please *do not forward* any part of this mail to anyone. The public %% announcement is not until May 19th, and we'd like to keep the %% information embargoed until then. %% You are receiving this mail because (we think) you run a Scanley %% server, and would want to have it patched before this security hole is %% made public on May 19th. %% References: %% =========== %% CVE-2017-892346: Scanley stack overflow in queries %% Vulnerability: %% ============== %% The server can be made to run arbitrary commands if the server's %% locale is misconfigured and the client sends a malformed query. %% Severity: %% ========= %% CVSSv2 Base Score: 9.0 %% CVSSv2 Base Vector: AV:N/AC:L/Au:N/C:C/I:C/A:C %% (See https://nvd.nist.gov/CVSS/Vector-v2.aspx for how to %% interpret these expressions.) %% Workarounds: %% ============ %% Setting the 'natural-language-processing' option to 'off' in %% scanley.conf closes this vulnerability. %% Patch: %% ====== %% The patch below applies to Scanley 3.0, 3.1, and 3.2. %% A new public release (Scanley 3.2.1) will be made on or just before %% May 19th, so that it is available at the same time as this %% vulnerability is made public. You can patch now, or just wait for %% the public release. The only difference between 3.2 and 3.2.1 will %% be this patch. %% [...patch goes here...] %% \end{verbatim} %% } %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% \foilhead{Distribute the fix publicly} %% In a single, comprehensive announcement, you should describe the problem, give the CVE number if any, describe how to work around it, and how to permanently fix it. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Packaging, Releasing, and Daily Development} Open source: release and development are in parallel. What does a new release mean? bug fixed. new bugs introduced. new features added. incompatible changes introduced (e.g., data formats). Release numbering. Most important for people who don't follow the project on a daily basis. be consistent. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Release number components} Release numbers are groups of digits separated by dots. For example, Singer 5.11.4. There is no limit to the number of components, but most projects do not go beyond three or four. Descriptive label, e.g., Singer 5.11.4 (Beta). Other qualifiers, Stable, Unstable, Development, RC (Release Candidate). a.b.c - a is major number, b is minor number, and c is micro (patch) number. Increments in the micro number are essentially for bug fixes only. Increments in the major are for big changes, new features. An parity (even/odd) of the minor number indicates the stability. a.b.c.d - d is called build number (incremented every time the software is built). 0.1, 0.2, 0.3 - initial development %?? leeway %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Release branch} A release branch is just a branch in the version control system (see branch), on which the code destined for this release can be isolated from mainline development. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Packaging} The point of the source package is to unambiguously define the release. scanley-2.5.0.tar.gz (for Unix-like systems) scanley-2.5.0.zip (for Windows) \newpage \begin{verbatim} $ ./configure $ make # make install \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Candidate releases} Many projects prefer to put out release candidates first. Why? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Signatures and checksums for package tarballs} scanley-2.5.0.tar.gz scanley-2.5.0.tar.gz.asc scanley-2.5.0.tar.gz.md5 (scanley-2.5.0.tar.gz.sha256) md5sum \begin{center} \includegraphics[width=0.60\textwidth]{fig/CPT-Hashing-File-Transmission.png} \end{center} (from wikipedia) A signature is created using the private key of the signer. The signature is verified using the corresponding public key. emacs-26.1.tar.xz.sig {\tiny \begin{verbatim} -----BEGIN PGP SIGNATURE----- iQEzBAABCAAdFiEE1AWqLIYsVPF+7mvg6LzXhmr8+XgFAlsL9voACgkQ6LzXhmr8 +Xiv8gf+KwpUcTcrDYW+wcOpn0VtpCVrYZQUoz9WWD0N3zDmlNfk+O+tV9q0vEWF gD6aiflkGJ0hM16tV7kqlAkeM6CrZqnfgaVoJFrLQhjaEv9qm1g8Bb21RgZMeZOp W+Zoojk9a9UipLlLvfMR9tDP9CEXFls7sXgBpPFiMiQLsKn2B2cv9mkHUp4mfM3t J6OISfrdgPSX1QtIe6zZlhJjmIgK1vA7I4Ce4CDuY9HmuqiZowq2h0Vwbcw5AEsa 5greYvtX+I2f6Uxppm6fdiS2rFaVNm5zTqH1bPvKxLZKlQs9WokJ3lOG/xgH1Wrj 5pIdAsIIS7wHaqj4jOwDA4IDjoNyVw== =fILP -----END PGP SIGNATURE----- \end{verbatim} } {\tiny \begin{verbatim} alice% gpg --output doc.sig --detach-sig doc You need a passphrase to unlock the secret key for user: "Alice (Judge) " 1024-bit DSA key, ID BB7576AC, created 1999-06-04 Enter passphrase: blake% gpg --verify doc.sig doc gpg: Signature made Fri Jun 4 12:38:46 1999 CDT using DSA key ID BB7576AC gpg: Good signature from "Alice (Judge) " \end{verbatim} } %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Managing Participants} Community and motivation. Humans have a {\em built-in desire} to work with other humans, and to {\em give and earn respect} through cooperative activities. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Create constructive atmosphere in the community} \underline{Delegation}. Ask someone else to take on the task. Purpose: not just about getting individual tasks done, but also drawing people into a closer commitment to the project. Make the assignment of a task (ticket) in the form of an inquiry. {\tiny \begin{verbatim} Assigning this over to you, jrandom, because you're most familiar with this code. Feel free to bounce this back if you don't have time to look at it, though. (And let me know if you'd prefer not to receive such requests in the future.) \end{verbatim} } \underline{Follow up after you delegate}. \underline{Notice what people are interested in}. The more aware you are of what different people want out of the project, the more effectively you can make requests of them. Demonstrating an understanding of what they want in itself is useful. \underline{Praise and criticism}. Both show attention. Be specific rather than generic. Both can be diluted by inflation. Detailed, dispassionate criticism is often taken as a kind of praise. Most people respond pretty well to criticism that is specific, detailed, and contains a clear (even if unspoken) expectation of improvement. \underline{Prevent territoriality}. When people sense a "no trespassing" sign, they stay away. For example, author names. \underline{The automation ratio}. \underline{Automated testing}. Regression testing, regression test suite, regression. Unit testing, a unit test suite. % skip: Treat Every User as a Potential Participant %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Share management tasks} "Manager" does not mean "owner". {\em Responsibility without monopoly}. What should we do in case of conflict: two or more people want the same role? Patch manager. Translation manager. Documentation manager. Issue manager. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Transitions} Personal circumstances can change. {\tiny \begin{verbatim} > If you wish to replace me with some one else, I will gracefully > pass on the role to who comes next. I have one request, which > I hope is not unreasonable. I would like to attempt one more > release in an effort to prove myself. I totally understand the desire (been there myself!), but in this case, we shouldn't do the "one more try" thing. This isn't the first or second release, it's the sixth or seventh... And for all of those, I know you've been dissatisfied with the results too (because we've talked about it before). So we've effectively already been down the one-more-try route. Eventually, one of the tries has to be the last one... I think [this past release] should be it. \end{verbatim} } The most important factor in asking someone to step down is privacy: giving him the space to make a decision without feeling like others are watching and waiting. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Committers} A committer is someone who has commit access: the right to \underline{make changes} to the copy of the code that will be used for the project's next official release. A committer has the ability to put changes into the {\em master} copy. There are always many people who feel competent to make changes to a program, and some smaller number who actually are. How to choose a committer? The Hippocratic Principle: {\em first, do no harm}. Good judgment. Good personality. If you have 100 committers, 12 of whom make large changes on a regular basis, and the other 88 of whom just fix typos and small bugs a few times a year, that's still better than having only the 12. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Credit} Credit is the primary currency of the free software world. Participation in an open source project can indirectly have monetary value, because many employers now look for it on resumés. When small contributions are acknowledged, people come back to do more. Keep accurate records of who did what (be specific), when. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Forks} "Social forks" versus "short forks (hard forks)". \underline{Handling a fork}. A social fork is not necessarily a bad thing (e.g., GCC/EGCS fork). Keep calm and remember your long-term goals. Don't remove someone's commit access in your project just because she decided to work on the fork. \underline{Initiating a fork}. {\em Most forks do not succeed, and most projects are not happy to be forked}. Take all factors into account in evaluating the potential success of your fork. Line up support privately first, then announce the fork in a non-hostile tone. Granting all committers of the original project commit access to the fork, including even those who openly disagreed with the need for a fork. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{User satisfaction} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Master branch gatekeeper} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Epics and story points} Sprints. Timeboxes. TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The Economics of Open Source} Software developers must be paid. Office space and network bandwidth. Proprietary software: monopoly-controlled royalty streams based on per-copy sales. Imagine something that everyone needs but no one needs to own. For example, a company needs a web server, but it does not want to make money from it. Maintainance is also a burden. - Paid developers: informal subsidy, salaries. - Unpaid developers In-group and out-group developers. Unpaid labor for someone else's benefit. - Funding sources Money -- hire good programmers -- influence -- voting power -- voting block. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Forces of Chaos} A key developer suddenly loses interest. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Corporate Involvement} Sharing the burden. Reduce cost of development incurred on individual companies without sacrificing the benefits. Ensuring maintenance of infrastructure. Companies sell services dependent on open source software. Establishing a standard. Include the standard into open source software to make it popular. If the standard becomes popular, the company becomes profitable. Creating an ecosystem. Supporting hardware sales. Hardware is useless without good software, vice versa. Undermining a competitor. Marketing. Brand marketing. Proprietary relicensing. Resell open source software by integrating it to proprietary software. Not a "pure open source play". "Open source is just a way of software development" to "open source is a way of life" spectrum. Start the project or join in the project? Leadship or just one voice? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Government Projects} Elected officials. Publicity events. Exposure event. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{Be Asynchronous} Wikipedia versus Encyclopedia Britannica. Distributed workflows. %https://ben.balter.com/2020/03/18/tips-for-working-remotely/ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The Zone} Do not interrupt a deep worker when they are in The Zone. Why? %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \foilhead{The Kanban Method} Taiichi Ohno. Introduced in 1940s, 1959??? by Toyota. A great view of the status of the project. Immediately know who is doing what by just looking at the board. Each task is represented by a card. Each movable card can be in one of {\em phases}: Backlog, Work in Progress (WIP) and Done. Usually, as the work progresses, you shift the card rightward. For software development, we could have Backlog (requirements), Develop, Test, Documentation, Done. Priority. Order cards in each phase by their importance. Start with what you are doing now. WIP limit. Don't overwhelm the developer by too many tasks (multitasking). Definition of Done or Done Rule. Lead time: time between task creation and completion. Visible to customers. Cycle time: time between task start and completion. Visible to employees. Burn up diagram (Cumulative Flow Diagram). Burn down diagram. Pull work instead of Push work. One color for each team member. Great! Good Kanban software: \href{https://kanboard.org/}{Kanboard}. \end{document}