The Blog of Manfred Touron

Paris P2P #8 - Last News from Berty

A talk I gave online during Paris P2P #8.

#conference (20) #presentation (13) #slides (11) #berty (17) #parisp2p (10)

Feeling Lucky

Let’s calculate the probability of:

life appearing on a planet
life evolving beyond bacteria into complex creatures
creatures developing abstract thinking
inventing programming
being a winning spermatozoid and being born
being born in a time and place where computers are invented and accessible
in the period where the active development of IT coincided with your formative years

The probability would be 0.0000…, with so many zeroes that, if they were grains of sand, they would fill our whole Universe.

I’m feeling very lucky to be that little “1” at the end of the long trail of zeroes.

I’m computer scientist who started developing at the beginning of a new IT era, which means:

I experienced multiple stages of IT evolution
I started early enough to need to learn low-level things that help me have a different view of how things work comparing to people who started later
I started late enough to have a lot of tools and development comfort, so I can focus on the project instead of focusing on the old constraints

Some might say: “Of course you’re feeling lucky living in a big city in a well-developed country, having such easy access to technology and education”. But another thing I like about the current era is how widespread the technology is and how many opportunities it gives. I worked with many people from other countries, thanks to the network that unites us. People have access to learning many things and be at the age of innovation, regardless of where they live. The world as a whole is getting more open and connected each day, and I’m very lucky and grateful to witness it and be a part of this process.

Photo Credits: Brett Jordan & Clément Falize

Challenges of Open-Source (presentation)

A talk I gave at Lab 42 @ Veepee.

Link to the presentation

#code (51) #conference (20) #presentation (13) #slides (11) #veepee (6)

Challenges of Open-Source

Can I – and should I – contribute to this project?

Most projects will be happy to accept any kind of contribution. If, for any reason, the mainteiners don’t want contributions, they can write in README.md or CONTRIBUTING.md files. Though it’s quite an unlikely scenario that people wouldn’t want any contribs to their public repositories – I’ve never seen that.

If they don’t want to maintain a project and don’t want any activity on it, the author can simply archive the repo to make it read-only. For example: https://github.com/boltdb/bolt. In this case, you can clone their repo and continue developing your own branch.

If their CONTRIBUTING.md file says that they dont like contributions, you will have a message the first time you open a PR, saying “you should take a look at the contributing.md file”. But even on repos with strict contribution policies, you wont hurt anyone by opening a PR – they might just ignore it, but they also might reply with a nice message, or let a bot reply for them :)

However, even though people generally don’t refuse contributions, you may stumble upon a project that is not very contribution-friendly. For example:

Maintainers are too proud of themselves and will actually refuse to admit that you helped them, saying: “Yes, I managed to do that, you know, I’m so much smarter than you”.
People that won’t be respectful of your contribution (sometimes knowingly, but most of the time because the are beginners on GitHub), and will just take your idea and recode it or find a way of pushing your edit with their name as an author.
People that are too perfectionist of arrogant; they will accept your help but ask you to be as perfect as they are, “Thank you for your idea (that helps my project a lot), can you please: add a lot of docs, a lot of tests, a lot of …, because I/we have very high quality standard, you know”.

In most cases, those behaviors change over time to become more open and respectful. But if you want to avoid things like that in the first place, you can check the history of the individual or organization that created the project, to see how they act.

Good signs to look for

First of all, check the other contributions to this project – it’s easy to view other accepted/refused contributions, analyze what was done by the contributor, analyze how open was the maintainer to accept the contribution, how long it took to accept or reject it.

If the current repo doesn’t have much activity, you can check the other repos from the same author/organization. One of the main concepts of open source is transparency. GitHub will help you get most of this information easy, you can even have more info by using alternative tools (git log, external websites, etc).

Indicators that a repository is contribution-friendly:

Project is “fresh” – the repo has some recent commits, author has recent GitHub activity.
Readme or Contributing files have some kind of a “contributions are welcome” message.
Website has a ribbon “fork me on GitHub”, or a messgae “See a typo? Propose a change on GitHub”.
The project is well-documented so that other developers can easily run it.
The author has some “open source lover” in his/her bio.

Browsing for projects

If you don’t have a specific repo in mind and just browse to find a project to contribute to, GitHub has a few standardised ways of explicitly asking for help:

GitHub’s official “help wanted” issue/pr label

This label is a way for authors to openly ask help from the community. Sometimes it will be for a feature idea they have in mind, sometimes for bug fixing, sometimes for feedback/reviewing. GitHub will handle those labels in a custom way, a repo could say “hey we have 3 help wanted issues”. Over 600k issues on the site have this label.

You can also check for a particular author.

GitHub’s official “good first issue” issue/pr label

More info about using labels on your projects .

This label is similar to “help wanted"б but with a specific flavor: available for beginners :) This label will also make GitHub react differently by making the information more visible to you in different places.

“Good first issue” issue something that considered relatively easy by the maintainer, but something he’d greatly appreciate some help with.

My own repos also have issues with this label ;)

GitHub’s unofficial “help wanted” project topic

Project topics were added recently, most of the time you use them to indicate the main areas of a project: “privacy”, “container”, “web”; but some folks are also using some project topics to ask for assistance:

If you’re still not sure if your contribution would be relevant, you can open an issue, saying something like: “Hello, I like your project and was planning to contribute, what do you think of my contribution idea: … ….”

Taking a leap

If you’re hesitant about making your first contribution, the best thing to do is to just go for it. Getting the hang of GitHub might take a bit of time, but and the fastest way to do it is dive in and be active.

Besides, not all contributions require coding. Something like typo fixing might not be very glamorous, but you will see that your contribution is accepted, and that you actually took part in a project to make it a little bit better – it’s an inspiring feeling.

Another example of an easy contribution is this: if, while installing the project, you had some issues that you eventually solved, it would be very appreciated if you update the installation instructions.

If you make a contribution that is rejected, but you still think it should be there, another part of the open source is the right to modify! Just fork the project; read the original license and explain in the readme why you fork the project, how different it will be, etc. Most of the time, the original author that rejected the contribution will be happy to let you link your fork in the original project’s readme or at least in the rejected pull request.

The “worst” that can could happen is that you lose some time on a contribution that is rejected. It’s a bit disappointing, but not life-shattering. And, most importantly, the things that you have learned while working on the contribution would stay with you, no matter if it’s accepted or not.

Fear of exposing your code

Some people are reluctant to publicly share their code because they are concerned with the potential reaction of the future employers or colleagues.

Here, people are assuming that their code isn’t great, or that they aren’t using some cool libraries, etc; and that they would be shunned for it. But most of the time, the code is ok, and people aren’t going to judge anyway. Even if some potential employers were indeed to dismiss your candidacy just because they’re picky about the projects you contribute to or libraries that you use, you’re probably better off not working for them anyway.

And if your code were truly awful, your PRs wouldn’t get accepted and won’t show on your profile in the first place – so, if your contributions are accepted, it means they are ok to be viewed :)

README and documentation – best practices

More often than not, the concern about making a project open-source-ready is more about “checking we don’t let out the code we aren’t proud of” than actually “making the project easy to contribute”.

At a bare minimum, you can just open your project with no changes. But something that is quite helpful and not too time -consuming is creating a good README. This file will be read many more times than any other doc.

README.md should allow someone to quickly discover what your project is about, how to install and use it, which features to look up to.

Readme is an index where you could put all the important and relevant things:

Wiki
Demo
Documentation
Installation instructions
Embed a screenshot/screencast
Changelog (if it’s important enough, you can even place it directly into the Readme)
If you use npm, link to npm; if you use GitHub releases, link to the release page

You can specify some things about your approach and philosophy, for example:

“This is a side project that I do not plan to maintain, but feel free to fork it or open PRs”
“This project was made with a specific goal in mind, sorry but I won’t accept big design changes”
“Philosophy of this project: stay simple”

It’s a good idea to explicitly write that all contributions and feedback are appreciated, and people are welcome to open issues if they want to share their ideas.

If the project has a planned future, link to the corresponding issues if you want to receive feedback and ideas on them, or to and external public Trello with the issues.

If you are very cool, you can link to the projects that are the alternatives of yours, and explain what the differences are.

Unfinished README or project

Something you can often use in an open source project is the “TODO” keyword. If you currently don’t have time or inspiration to write a certain Readme section properly, you can add the “Installation” title and whire TODO under it. It will show that you have it in mind for the future and didn’t just forget about including it, and will also show other users that you would really apprecite if someone helps you complete the section.

If your project isn’t finished, it’s not a problem, just write it in the READMe – some people will bookmark the project for later, because they are interested to know how it will evolve over time.

Creating the project documentation

Write the initial doc for yourself, something you would regret not having if you open the project in two years. What are the most important things that you would need to know?

Then, when you have more time and energy, you can expand on this crucial doc. Documentation will also expand as you get explicit or implicit feedback from your first users.

No time for maintaining a project?

Not having time/energy to maintain a project can be a concern – or, rather, an excuse – that prevents from publishing an OSS project.

It’s actually rare that a project takes an overwhelming amount of time. For one, your new project will probably unused or used by just a few people for a long time. And as it grows and gets more users, it’ll be easier to find people who want to maintain it.

Being inactive is not a dealbreaker, especially if you clearly describe the situation.

In your project’s README, say something like: “Sorry, I don’t have much time to maintain it”.
Add the “help wanted” issue label to get more active help.
Set up a Patreon and define a way of receiving cash if someone needs something specific in a short amount of time.
If you’re not planning to maintain it at all, suggest your readers to check out some similar projects (bonus points if you give links to some options), or to contact you if they want to take the repo over.

Worst thing to do is to make your project unavailable (delete it) – this may break others’ software. Rather, put the repository into read-only mode (archive it), so that people can use it without any support if they want to, or fork it and continue developing their branch.

More thoughts on time management and OSS

Some companies give some time to work on open source (1 day per week)
Some people prefer to work part-time (4 days for their employers) and 1 day for themselves by doing open source
You can consider open source as an activity you can do on weekends, in the evening

Most of the time, if you remove the constraints of work (forced roadmap, forced topic to work on, delivery pressure etc), you would be coding for pleasure and fun, and you’ll be motivated to do it, just like you do any other thing you enjoy.

You can read my article on the subject, Coding useless stuff, or check out my video from the Paris P2P festival.

SEO and promotion

“SEO” sounds like something evil and corporate, but “search engine optimization” is often used for good. When you type a problem and immediately see a Stackoverflow link discussing and solving this exact problem, it doesn’t feel like you’re being tricked by marketing. And this match occured due to the power of SEO.

People who look for specific things

Project title and description are very important – not only for SEO, but also because they show on a preview when a link is shared.

The next in importance is README. Think what kind of people will need this project, what kind of queries they put into the GitHub search field, and add some introductory paragraphs with new keywords. Of course, keep the text coherent and use the words and their combinations that are most relevant.

People who are just browsing

Use project topics to add the technical ecosystems and also usage ecosystems. You will be listed for people that want to list “everything related to this domain”.

You can also list your project on awesome lists – there are plenty, it’s easy to add your project to a list with a small description that can help people interested in a topic to find it easily.

More tips for being discovered

List your project in a README of a related project. For example, if you create an SDK for another company, you can be listed in their doc and their repos. It could even be an alternative/competitor project, and your project could go into the “Alternatives” section of their readme file.

Protomote it on Twitter, in community chats. Most of the languages have a Slack or equivalent where you can post your project written in this language.

Make open source contributions to other projects using your own project. If your project is a library that addresses something, you can open pull requests on other projects to add yours as a dependency: “Hello, this PR uses my project, which gives you such and such advantages”.

Answer people’s question on StackOverflow, GitHub issues, etc, and link to your project when you think it can be relevant to the answer. People would click on the link to analyze your project, and then, if your readme is understandable enough, they will point to it by themselves to help other people.

Keep in mind that, in most cases, project recognition takes time. It usually rises in peaks, and sometimes you need to wait until someone famous tweets about it :)

Once again, any kind of search optimization can be done later – you can release your barebones project early, and add the docs, SEO, etc. later.

Is it possible to make money from OSS?

Some ways open source can improve your income, directly or indirectly:

You can make OSS for your company and get paid indirectly for doing open source
You can consider OSS as your best CV, a proof of your skills and work ethics, and lend good jobs thanks to it
Setting up Patreon and GitHub sponsors
Taking bug bounties and be paid for doing stuff others asked you
You may receive prizes/rewards (as I do from Google), kind of donation
Your OSS project can help with or be a part of another project that brings you money

A lot of good brains are acutlaly working on new models to allow people to live from open source. People are looking into ways to democratize bug bounties, etc, in order to allow some companies to have no full-time employees, only the external contributors that are well-ranked thanks to their contributions.

#code (51)

Flexibility in Project Development

There’s a “problem of the extremes” that is often encountered in project development. The issue is not with each of the methods per se, but with wholeheartedly sticking to a certain method or approach, regardless of the circumstances. Most of the time, people do it with the best intentions, sincerely thinking it’s the “most optimal” way. But, just like different clothes can be good for different weather conditions, there is no path that is the “most” optimal in all situations.

Some things that could be good ideas – or not – depending on the circumstances:

Having lots of unit tests, or just a few, or none?
Pull request being reviewed by everyone on the team, or only some people, or merged without a review?
Having a separate issue explaining the plan, or just opening a pull request right away?
Sometimes it is a good thing to ask for a roadmap, sometimes it isn’t (R&D – research and development)
Sometimes it is a good idea to have a lot of repositories or folders, but most of the time a monorepo will be better.
Sometimes it is a good idea to abstract code, most of the time it isn’t (people often abstract too early based on what they imagine the code would become later. Doing that makes it harder to read the code, change a small part of it, etc. Abstraction is good when you have a clear practical explanation for it).

Choosing a single path is a mistake I made regularly, but I try to be aware of it now and always analyze my approach. For some people I meet, this issue remains unresolved, getting deeper over time. Most of those cases are due to perfectionism – when a person wants to “do one thing, and do it right”. They genuinely like their project and don’t want to mess anything up. However, in the long run this “good intention” becomes a reason the project becomes globally “slow”, regardless of what the chosen “single rule” is. This also becomes a hot issue for arguing among the employees – since people who want to ship fast and perfectionists don’t get along with each other, half of your team will become disgruntled with the state of things.

You don’t need to try making everyone happy 100% of the time, but it is important to accept both extremes for everything: people, rules, cases, parts of the code. Embracing multiple rules that always have limits (implicit or explicit) in order to avoid making an inappropriate choice just because “it’s the way we do everything”.

For example, in a startup, you usually have these categories of tasks, based on how critical their failure is:

Vital. Anything related to payments, user data protection, security. If something fails here, your business will suffer severe damages or will be destroyed completely, so you should take extra precautions here.
Planned features that are well-prepared and have to be done. For example, things that competitors are doing, so they should be also implemented to keep up with the competition. Here, you should mainly focus on having operational review, and sometimes can tolerate letting some edge cases not be managed at all.
Pure ideas that may completely fail. Here, you should make everything possible to be very fast, but also to not complexify the codebase if you need to remove the feature. Basically, you should try to protect the rest of the system from becoming more complex.

Having a lax attitude towards vitals may eventually be catastrophic. But treating every feature as if it was vital greatly extends the development time and leads to a waste of resources. Ideas should be tested fast to get a quick feedback that will indicate if it should be pursued or discarded.

Stay flexible, do not hesitate to have not one but two or more processes; do not hesitate to say “this is the default expected behavior, but in some particular cases, another process is preferred instead”.

Here are a few approaches to the issue:

You can try to have better “exception handling” of the general rules, or multiple rulesets.
Another approach is to educate and encourage people to not just strictly stick to the given rules, but be adaptive. Then remove most of the hard rules and let people choose what they think to be the most appropriate “need” (not rule) for the current step.

I have some friends who own startups that also tried different things that are worth being considered:

Regularly, reset all rules and let the team update their own team rules. Most members of the team will collectively choose to apply some rules that work for them right from the day one, some will try to have no rules and only add some only when problems appear, etc. I think this method is very cool if you have the chance to have different autonomous teams, so you can experiment with multiple things at the same time and also “compare” with the others.
Another approach I like, “the rule of three”, is the one from the Swedish “parti pirate” which goes like this. Anyone in the organization can come up with an idea. Then they suggest it to a second person. If that person disagrees, the idea is rejected at this stage. If the person doesn’t have any opinion, they can recommend asking someone else instead. If the first person finds someone else who agrees with the idea, they look for a third person. Again, if that person disagrees, the idea is discarded, but if that person agrees, all three of them start implementing the idea, and are all equally responsible for it.

I like the philosophy of trying fast and being error-friendly. It even becomes a skill to be prepared for the bad decisions, since some inevitably will be made. Instead of finding the best protocol, the best library, anything “best”, we concentrate on finding the most viable “upgrading strategy” in order to support having a first choice that is just okay, and then switch to a better one (which most probably is still not the best, but better than the previous one).

#management (15)