Open development tools
Stefano Moia¹
1. Basque Center on Cognition, Brain and Language, San Sebastian, Spain
10.11.2020
An overview to jump into your own first open development project à la Brainhack
| smoia | |
| @SteMoia | |
| s.moia.research@gmail.com |
Stefano Moia, 2020
1. Basque Center on Cognition, Brain and Language, San Sebastian, Spain
Open development tools
Stefano Moia¹
10.11.2020
An overview to jump into your own first open development project à la Brainhack
Open Development
Open (Source Scientific Software) Development: the idea of developing a scientific tool:
- in an open and public way
- sharing it from the beginning of the development
- fostering a democratic community of contributors in support of the project
- acknowledging all contributions
- using version control and (automatic) testing
Two main elements: the tool itself and the community around it.
The tool or project is not necessarily code based!
Version Control
Version control systems are a way to manage and track changes to files.
VCS can be also found elsewhere (e.g. Wiki, GDocs, Box, ...)
Content
Aggregation/delivery
Does any of these situations look familiar?
I can't work on that project now because my colleague/friend/dog is working on [a different part than what I'd modify of] it at the moment...
A classic git(Hub) flow
Create branch "dev"
Commit
Merge dev into main
Diverging main
Merge main into dev
"Main" branch
Main
Dev
Bug
A classic git(Hub) flow
Create branch "dev"
Commit
Merge dev into main
Diverging main
Merge main into dev
"Main" branch
Fork ("upstream" vs "origin")
Pull from upstream
Merge origin/main into dev
Clone (local repository)
Pull Request
Pull from *
Push to *
Main
Dev
Upstream
Main
Origin
Dev
Main
(local)
Pull requests and Reviews
Pull requests and Reviews
Some suggestions for...
- Keep you contribution small and focused
- Make your contribution as clear as possible
- Use a review as a learning experience
- Be patient: reviewers might ask you some more work than you expected, but it's always to improve your work.
- Be kind and patient
- Don't limit your review to the apparent changes
- Keep your review to what's necessary for the contribution - if it would be nice to ..., write it doan and wait for the next contribution
... Authors
... Reviewers
Take home #1
Working with git/Hub
can be challenging, but it lets you work in parallel on the development of new features, without disrupting the "main" version of your project.
Bonus: it can force a team to double check projects!
Guiding the development: issues
Guiding the development: milestones
Guiding the development: labels
Not all communities use labels, and those that use them might use them differently!
!
Take home #2
Guide the development of your project using issues, milestones, and labels:
-
it will make your life easier and better organised.
-
it will make your project easier to understand for third parties.
Who's in charge?
Open Development is not just about the tool being develop.
The greatest thing you can develop is the community around it!
- The development can be very driven and focused on key points.
- Decision making is quick.
- Users might not be engaged enough to value your project.
- One developer = more time needed for new features, less reviewing.
- Less stability in the group = more time training.
- The development can become more based on the help of the volunteers.
- Decision making takes a bit longer.
- Sense of involvement and responsibility might increase (stable) contribution!
- Many developers = less time needed for new features and better quality!
- More stable people = more mentors.
Not all contributions are the same...
Independently from its kind, projects can have different types of contributions.
Different communities can have different requirements or follow different workflows.
Enters the contributors' guidelines
(and a code of conduct).
... but all should be recognised
Depending on the community and the governance scheme, contributions might be recognised differently. Explicitly writing down how the community does it helps new contributors to join.
One way of recognising contributors is the all-contributors specification.
Take home #3
There are advantages and disadvantages in any form of governance - choose yours from the start and state it clearly.
In any case, don't forget to recognise other people's work and take time to develop the community!
Testing 1 2 3 ...
Testing a project is as important as developing it.
Arguably, it's even more important, so spend time on it!
There are multiple types of tests:
- User tests: a person (user) uses the tool and make a report on it.
- Automated tests: developers write tests to be run after each change.
Releases
Making your project public is important: it will attract more users/readers and (possibly) more contributors.
Create a "release", and if the project is code-related, package it and distribute it!
License your work
A work that is not licensed is not public (paradox!)
There are many (open source) licenses to pick up from, not only code-related.
www.choosealicense.org
Deploy (release) it and give it a DOI.
One last thing: Let bots do the hard work
CI/CD workflows are your friend.
- Continuous Integration: frequently integrating new changes into the main branch of a tool. Normally, workflows run automatic steps at each integration, e.g. automatic testing.
- Continous Deployment: frequently deploying (releasing) new versions of a tool using automated workflows (e.g. right after integration).
Workflows can require a bit more work to be set up, but they can save a lot of time and energy in the long run!
One last thing: Let bots do the hard work
Automated workflows are your friend.
Everything can be automated, from testing to releasing (packaging end etc.).
Workflows can require a bit more work to be set up, but they can save a lot of time and energy in the long run!
Take home #4
Test and release your work (frequently).
License it and make it citable.
Possibly, automate these steps!
Call to arms: jump into your next project!
That's all folks!
Thanks to...
...the SPiN group @ BCBL
...you for the (sustained) attention!
... the Brightlab - ANVIL group@ Northwestern
... the physiopy contributors
Stefano Moia, 2020
Oh, and don't forget!
Oh, and don't forget!
Open development tools (Brainhack Donostia 2020)
By Stefano Moia
Open development tools (Brainhack Donostia 2020)
CC-BY 4.0 Stefano Moia, 2020. Images are property of the original authors and should be shared following their respective licences. This presentation is otherwise licensed under CC BY 4.0. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/
