2016-05-12 Open source policy draft 0.2.md

DRAFT: Open source policy 0.2

May 12, 2016

Scope? System developer that want to convince managers or PIs?

Please make sure you're logged into Google, otherwise we cannot attribute your contributions.

The basics

1. Open source your project unless you cannot (open by default)
   1. Unless there is a compelling reason not to do so, provide the source code in a publicly accessible source code repository as early as possible
   2. Work to mitigate fears from others in your project about open-sourcing
      1. See "Fears of open sourcing & some ways to handle those (which we came up with and should publish somewhere)"
2. Attached a suitable license to the source code repository, and ensure compliance with third party software licenses 3. Article on open source license compatibility 2. http://www.wegtam.net/article/combination-and-compatibility-open-source-software-licenses 4. Unless there is a very good reason not to, you should use an OSI-approved Open Source License. 3. If your institution or project already has license policy, use that one. 4. Otherwise we advise choosing one of the license here (link), depending of your preferences 5. If you cannot use an OSI-approved Open Source License, at least adhere to template of OSI-approved Open Source License or Free for academic use Licence.
3. Open development should be expectedenforced from the start of the project, if possible Read and apply 10 simple rules for Ten Simple Rules for the Open Development of Scientific Software 6. Development should be done in a publicly visible version-controlled repository 5. This can be an institutionally hosted repository or externally hosted at e.g. GitHub, BitBucket 6. You should use semantic versioning (see http://semver.org/) appropriately at a later stage of the project (e.g. when first external user becomes involved) 7. You should make it clear what is being communicated via which channels "Channels should be well documented" 7. For guidance of what channels are useful see this document 8. Produce user documentation, README file, how to install the software 8. All decision-making should be transparent and on the recognised project communication channels 9. Avoid "private" decisions (e.g. discussing with your co-developer in the coffee room without then recording the decision publicly) 10. Have a public roadmap 11. Strive to include the community in decision-making, where possible 9. Be clear how people can contribute to your project 12. Make it clear you really want people to contribute 13. Make it clear how to set up your development environment and build the software 14. good practice is to create CONTRIBUTING file, that describes how to contribute (some more details on GitHub docs) 15. Create guidelines for common contribution tasks 16. Have a code "style guide" and build enforcement into your development workflow 1. For examples: https://github.com/google/styleguide/ 2. Use linters to enforce adherence to the style guide (example: eslint) 17. Make sure contributions are allowed and compatible 3. Contributions should be in scope 4. Contributions should be checked for license compatibility (see: http://www.gnu.org/licenses/license-list.html) 5. Contributors should have the right to contribute (see copyright) 18. Decide if you need a formal Contributor Agreement 19. Consider labelling issues by "ease of engagement" to encourage new contributors 10. Ensure your software has accessible and pragmatic documentation Different aspects of documentation 11. Your project should have a Code of Conduct in your repository and linked from your website ("Be nice") 20. Make people feel appreciated for their contributions - thank them 21. Don't assume you know why someone did something, check why 22. Examples are here: contributor covenant 12. Use existing tools to help manage your software, rather than creating your own (see link on OSS-Watch website, http://oss-watch.ac.uk/resources/communitytools)

Developing the community

4. Work to build a community around your software 13. Document what your software does! 23. Publish use cases 14. Publicise your software through conventional and non-conventional means 24. Consider nominating "evangelists" from your community 25. Use videos to help. Consider getting recognised scientists to record / appear in these 26. Consider the types of users you wish to attract when presenting your software at conferences, meetings, etc. to grow its community - e.g. end-users, developers, user/developers 15. Create opportunities for participation 27. For instance hackathons, tutorials, workshops 16. "Piggy-back" on existing events that your community attends 28. e.g. BOSC, ISBE 17.
5. Publish your software in a DOI-issuing repository 18. You should publish under the same license 19. You should get a DOI for each major release 29. And versions associated with publications coming from your project 20. Zenodo and FigShare both enable DOIs for software https://guides.github.com/activities/citable-code/ 21. Advertise the DOI at the top level of your repository and in a CITATION file

Striving for the meritocratic bazaar

6. Become more open as your project matures 22. Be transparent about your current governance model 23. Formalise your communication channels for your contributors 24. Open up your decision-making 30. For examples of different open source governance models see: http://oss-watch.ac.uk/resources/governancemodels 25. Formalise roles in the project and the "promotion path" 31. How do people become associated with key roles? 26. Recognise that "you are not your code" 32. Be able to separate criticism of your software from criticism about yourself

Fears of open sourcing & some ways to handle them

(See Victoria Stodden's work on identifying fears: http://stanford.edu/~vcs/papers/SMPRCS2010.pdf )

• "My software is such a bunch of hacks that no-one will want to contribute to it"
  • If it's closed, no-one can contribute to it anyway. If it’s useful and open, then people could still contribute, even if the code quality is not great
  • Even inspiration (how things were done once) is worth sharing
• Someone takes my software and sets it up as a service, but wrongly. This would reflect badly on my original software (e.g. they used the wrong data).
  • Way #1: You can use trademark enforcement of the name to make it clear that this is not your or your software's responsibility
  • Way #2: Document your setup [better], automate it (use Docker or similar tools); keep communication channels in order
• "My group's software (unique methodology, specificity, knowledge) gives our research a competitive edge that will be lost if we released our code in the open."
  • Research is way more than the software that facilitates it, and the software usually lags the ideas
  • If your edge is only the software, it's just a matter of time until you're no longer competitive
  • Your research is probably held back by the bugs you haven't found yet that others would
• "Other people need the 'right data' to be able to use my software, and I can’t give this to them because it’s protected/confidential/etc so my software is no use"
  • You can provide simulated/reference data which you should have in any case to help with testing
• "I am the expert in this field. I am the best person to build this software and don't see how letting other people contribute will help my software"
  • You may be the expert in your field, but the software is just a tool you are building. You are probably not the expert in all aspects of the software you are creating.
  • Providing open code and (open) training might help others to become experts as well
  • Documentation should help train new contributors: code comments, usage, development setup
• "It'll be impossible to open source software which we have developed in collaboration with companies / industry because it will be too complicated to resolve the legal issues"
  • You could consult an IP specialist such as OSS-Watch
  • Using an OSI-approved license will make it easier as commercial IP legal departments recognise them
• "Getting my code ready to open source will take a lot of time and effort"
  • The expected time benefits often outweigh the initial investment
    • You
    • (See: Taverna move to Apache incubator process)
  • It will help your internal development team
    • Enhances skills and CV
• "An open source license will put off life sciences companies"
  • Many life sciences companies use open source software - they care about functionality and support
    • Examples:
• "I'll have to support users" / “I’ll have to support users who are not in my field”
  • it'll foster collaboration and reputation in related fields, which can lead to new scientific collaborations and funding
  • Research funders want to see impact outside of your specific field
• "I will be liable if something bad happens when someone uses my software"
  • A good OSI-approved license will disclaim/waive liability better than having no license or an untested academic license
• My reputation will suffer if someone uses my software incorrectly, e.g. if someone publishes a paper based on results that use my software, but then if the paper must be withdrawn or retracted, my software may be blamed
  • ??? be it open or not, software will be distributed and used by people
• "I should be doing science, not open-sourcing software"
  • Science is fundamentally based on accuracy and trust in results. Open source code can be more trusted (cf security community) than black box solutions (see Shining light into black boxes paper)
  • Don't over do it if you don’t have time, just get what you have out there, it takes very little time
• "I won't receive any credit for my work"
  • Open-sourcing has been shown to improve citation and research impact in certain communities
  • Simply not true. It's very clear on github who contributes
• "People will scoop me"
  • Open-sourcing will tend to lead to more collaborations (leading to more publications) than other people scooping you
• "I won't be able to publish a paper about my research / about my software"
  • There are now many avenues for publishing software papers, and many encourage open source licenses
• "I'll have to pay for the cost of infrastructure"
  • There are many providers who allow you to use their resources for free if you are an open source project
  • Opening your source code does not require infrastructure on your part, you can just upload it to a repository hosting site like GitHub Notes from the all hands breakout group:

1. Basics

• The license must be mandatory
• It might be useful to include (maybe in the separate document) examples about licenses used by real software development projects in the life sciences and some guidelines on how to select a license
• Consider compatibility with libraries used
• Communication channels - github/bitbucket issue tracker might be enough, provide documentation (consider github wiki for that)
• the requirements about open decision making - this could be moved to the section of the meritocratic bazaar
• User documentation should be considered (added to the communication channels section)
• Documentation for developers is covered in contribution section

2. Fear of open sourcing & some ways to handle them

• People have particular technical problems, documentation for developers for FAQ of how to solve life science specific problems that are not usually found in standard OS communities: Large reference datasets, different use scenarios (commandline + web interfaces + Web services), database updating strategies, etc
• Detach yourself from the code, it does not describe you, everybody know that in the real world you often cannot do great code
• We are not trained CS, we are researchers, just get it out there
• You can organize a code review within your group, or some safe environment
• Document it in a way that installation is no problem.
• API > Installable > Dockerize > VM For reusability. But Docker and VM can really help distribute your functionalities when is not in great shape
• For niche software it's less important that the code has high standards, often its ability to document the details method is enough. On the other hand, for competitive software it’s important to have good standards or users will choose some other
• Setup a channel for feedback before they report a failure to the world
• If your concern is that only you have the data and you cannot share it, just have it out so people can read it, not even so important that it runs. En even better solution is to provide simulated data

2. Developing the Community & Striving for the meritocratic bazaar

• Who:
  • Define stakeholders
    • Ie. comms, developers, UX, …
    • Define goals and roles
      • Based on what is needed for projects
  • Define types of community
• Link data with software
  • Get data community involved and aware
• Promotion/supprort/communication
  • Many channels
    • Social media
    • Events
      • Conferences
    • Newsletters
  • Identify channel of target audience
    • Look for those with impact
  • Lots of effort to maintain channels
    • Consider if is it worth it
  • Effort vs impact matrix to help prioritisation
  • What is the purpose
    • Difference between give information (out) vs getting feedback (in)
  • champions/ambassadors to reach out
    • Identify them
    • Role on providing support
    • Benefits for champions
      • recognition/credit
• Use ontology/model for communities
  • To help describing commynity
    • ENVRI model?
  • To help discovery and connection of communities
• Support the promotion of the outcomes and services of the community
  • Within the community
  • With related communities
  • Outside the community
• Documentation (guidelines)
  • Content
    • What the software does, what is it for, how to use it, how to contribute
  • Types
    • Users, developers
  • Steps
    • Start with a quick start
    • More elaborated documentation
      • Document use cases
  • Identify who and what to document
• Software discovery yes, but not marry to one technology (ie. DOI)
  • Identifiers important
  • But maybe more important is to have software discoverable in a software registry or publication
  • Allow freedom but provide recommendation of technology/system
    • Ie. registration of tools, omics, tools,
    • Ie. identifiers: DIO, EPIC,