Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ELPP-3358 Choosing an open source component #9

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

ELPP-3358 Choosing an open source component #9

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98b68bc
Add draft ADR for choosing an open source component
davidcmoulton Jan 9, 2018
fbf7f4d
Add note about documentation
davidcmoulton Jan 9, 2018
18e785f
Style
davidcmoulton Jan 9, 2018
f8451c2
Respond to feedback
davidcmoulton Jan 18, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions adr/0007-choosing-an-open-source-component.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Choosing an open source component

Date: 2018-01-09

## Status

Proposed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd tag as many people as possible here, since this has wide-ranging implications


## Context

Using poor quality or unmaintained third-party software can be at the least inconvenient, and at the most downright dangerous: for example, it can fail to take advantage of the benefits from the latest technology, and security holes can go unpatched.

Using third-party software that is difficult to maintain integrated in our environment can make updating it difficult, time-consuming or risky.

Using software with an inappropriate license may present a legal risk, or may risk others choosing not to use our software because of the burden the license subsequently places on them.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit-pick: in the UK license is the verb, licence is the noun.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we need an ADR for British vs. American English 🇬🇧 🇺🇸

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

I used to have a yellow sticky note next to me on the wall that would remind me ;) I'm certain I've lapsed since then

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/muan/spiffing

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://twitter.com/PaulDJohnston/status/958362583580463107


We want to minimise exposure to these risks when choosing an open source component to use in the eLife code base.

## Decision
When choosing an open source component, care should be taken to try to choose something that is:

- licensed appropriately
- reliable
- well maintained
- sustainable within our environment

### Licensing

[should we specify this in terms of an explicit list of acceptable licenses, or in terms of what we need a licence to allow us to do?]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

considering we release everything with the MIT license, there is a compatibility issue (with GPL?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

an explanation on what it means to be 'compatible' with GPL licensed code: https://www.gnu.org/licenses/gpl-faq.en.html#WhatIsCompatible

and a list of compatible licences:
https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses

there is a lot of argument and untested legal theorizing on edge cases in most software licences. The only perfectly clear cut legal standing, in my humble opinion, is "public domain". Even the legality of closed sourced proprietary code becomes fuzzy if it's not 100% written internally in the same country in the same decade.

also, there are different types of code usage, like linking vs bundling vs compiling. is a compiled program with gpl licensed code required to also be licenced by the GPL? (yes). what if it's unmodified and uncompiled, or compiled to an intermediate format for an interpreter (javascript, python)? what if it's called from a script? is a script a program? all sorts of fun and games here.

Ian settled on the MIT licence for eLife, and while I don't agree with that decision ideologically, it is convenient for others for all sorts of reasons. Convenience and fewer barriers and very important to adoption if adoption is one of your goals.

I would be curious to find the licences of all of the dependencies our programs use and see which large groups emerge. I'm less worried about proprietary software sneaking in than I am about those who use a licence like MIT or BSD and then 'tweak' it, adding their own custom clauses.

+1 for a licence audit. I know observer and metrics and possibly lax are still GPLd.


### Reliability

- Check the code: are there any obvious code smells?
- Check the documentation: is there a README with a quickstart guide to get you up and running quickly? Collectively, is the documentation sufficient?
- Try out the code: does it behave as expected? Are there any idiosyncrasies in behaviour or usage that may indicate a design problem? A design problem may make bugs more likely, and may make it harder to fix them.
- Check the issues (open and closed): how many bug reports are there? How frequently are they reported?

These steps should help form a view of the likely reliability of the component.

### Well maintained

- Are there a decent number of recent commits? This will indicate whether it's under active development. Avoid it if it's not.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this stance a lot in javascript developers. recent activity is no indication of stability and is no reason to avoid a thing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is spuriously correlated with how big a project is, e.g. the Linux kernel has many commits per day even if some areas are very stable and the release pipeline is very long.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the other direction, if there is a single master branch with many commits per week it's an indication of in-stability. Number of existing releases could be a better litmus test for stability?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the JavaScript world things are moving so fast that something which lacks recent commits probably is out of date. I take the point that this doesn't necessarily apply in other environments.

- How far back do the commits go? This will indicate how mature the library is. Take extra care to assess its reliability if it's quite immature. Immaturity may be a reason to decline to use it if there is an equivalent, mature alternative.
- What is the average lifespan of pull requests? You might want to put in a pull request yourself: is the turnaround reasonable for your needs?
- How many people have interacted with the repo recently? A larger community is a good indication that bugs will be identified quickly, and improvements be made quicker than otherwise.
- How many people have merged in pull requests? A large component is more likely to be sustainable if more than one person has the ability to merge pull requests.

### Sustainable within our environment

Is there an obvious, easy integration path for its intended use, or will some hoop-jumping be required? The easier the integration is, the easier it is likely to be to keep it up-to-date within its eLife-useage context. This means easier overall maintenance of the eLife product.

## Consequences

Selection of all future open source components should go through this evaluation process.

This will help maintain the quality of eLife software, facilitate its reuse, and require less maintenance replacing unmaintained components so increasing the work not done.