Saturday, October 24, 2020

Rethinking open-source priorities - what is my time worth to me?

One day into trying to fix an issue I wondered if I was using my time wisely. Two days after that, and when I'd finally found the solution, I'm certain I hadn't been using my time wisely.

⏰⏲⏱

Cliche
Photo by CharClarPhoto - https://www.flickr.com/photos/charclarphoto/42437342612/

One of the things I like about contributing to open-source projects is that I can choose my priorities.

My thinking goes or rather went, that if I'm giving my time for "free" I should get to choose what I work on. I'm starting to think this isn't the best for me, or the projects I'm contributing to.

Back to the scenario, I started with.

One day into debugging the issue (an automated UI test that would fail periodically for no obvious reason) and I considered giving up. There were two things that kept me going:

  • I was really keen to understand the underlying issue.
  • I'd committed to fixing the bug. 
The bug was reported by a member of the project's core team and I'd created the test originally. I felt a personal responsibility to get it working. The bug was also something I (originally) thought I could fix quickly. Having the core team (who are paid to work on the project) spend their time on this didn't feel like a good use of their time.

Reflecting back on this, I was making a few (common?) false assumptions:
  • My time was worth less than those people paid to work on the project.
  • My time doesn't matter as it's just an open-source contribution. (I'm not being forced to do this.)
  • Because I'd started it I need to finish it.
  • Any external contribution to an open-source project is valid.
If this had been paid work, I would have stopped before the end of the first day working on this and said it wasn't worth the effort. If this had been my own open-source project I would probably have stopped then too. It wasn't worth the effort to spend more time trying to fix the issue. Having to occasionally rerun a test because of a false negative wasn't worth spending multiple days of effort. That time could have been used on something much more productive.
I would have been appalled to hear of someone being paid to work on the problem keep going for so long. So, why did I think it was ok for me to keep spending my unpaid time on it?

If you've read this far and think I was foolish and should have known better and stopped sooner. I agree.
Clearly, I need to reflect on this and better prioritize what I work on.

However, I think this highlights some important questions for people who maintain, lead, manage. or otherwise, influence people who contribute to projects. I'm thinking particularly of open-source projects but I suspect the same applies to closed projects within an organization too.
  • How do you ensure that all contributors are making the best use of their time?
  • How do you ensure an external contributor is doing something that is a good use of their time?
  • How do you prevent external contributors from becoming demoralized when stuck on tricky problems?
  • If you want external contributors, what are you doing to attract and keep them?

I think these questions matter because:
  • For paid workers, you want to ensure that the money spent on their time is being used effectively and efficiently.
  • For volunteers, you want to value and respect the gift of their time and ensure it is being used wisely.
  • For everyone, you want to make sure that no-one is stuck on something they should re-evaluate, abandon, or ask for help with.
    Previously I would have relied on people to speak up when they're stuck but this experience demonstrates that I don't always do this. So I shouldn't expect this from others.
  • For everyone involved, you want them to feel valued, appreciated, and that they're making valuable useful contributions.
    Some paid contributors will be happy to turn up, do something, and get paid without thinking about what they're doing and the wider consequences. But I expect having such people on a project that seeks open-source contributions can be a turn-off for would-be volunteer contributors.

Managing projects with both paid and volunteer contributors can be very tricky. I wonder if there are lessons from charities or other organizations that have both paid staff and volunteers which would be useful for those creating software this way?

If you have any thoughts on this, I'd love to hear them.
They could be on how you prioritize and know when to stop, re-evaluate, and when to keep going. Or maybe you have some thoughts about how project leaders/maintainers/managers can ensure that all contributors (paid or not) are making the best use of their time. Both personally and with regards to contributing to a project.

For me, the lesson I'm going to try and take forward is to think about giving my time to an open-source project and then focusing on what the best thing is I can do with that time. I'm going to try and put that time decision before I commit to fixing a bug or adding a feature.

post-script.
Yes, I did finally solve the issue. It was a timing issue (as they often are) relating to a light-dismiss dialog not always being closed. It's interesting, to me, to know this but was it worth two days of my time to find this out? Probably not. Would I have felt bad charging for my time to fix this if I was being paid? Yes.

Friday, October 09, 2020

6 tips for contributing to Open Source

 The following is based on a presentation I gave on the September 2020 WinUI community call.


Here are my tips

  1. Don't start with a Pull Request
  2. Follow the project's conventions
  3. Assume positive intentions
  4. Explain why. Don't say "should"!
  5. Focus
  6. Everything helps


Don't start with a Pull Request

If you're doing anything more complicated than fixing a typo or small spelling mistake, don't start with a pull request.
Engage with the project maintainers before you start doing any work.

You don't want to spend time on something that isn't wanted or that someone else is already working on. Nor do you want to build a solution that doesn't fit with what else is going on with the project.
It may also be beneficial to discuss possible ways to make the change, fix the bug, or add the proposed feature. You'll want to make the best use of your time, and maintainers or other people working on a project may have ideas and suggestions to help you.

You can "engage" with the appropriate people by creating an issue (if it's something new), commenting on an issue (if there is already on related to the work you want to do), commenting on a discussion, message board, email list, chatroom, or wherever else is appropriate for that project.
Aim to try and work the same way as others on that project already do.

Follow the project's conventions

Most projects include a document on how to contribute. Most of them include a note about not starting with a pull request. But there's more in there too. If a project has one, be sure to read the contributing.md document and follow what's written there.
If a project doesn't have a guide to contributing, ask how to get involved. And, maybe suggest a guide to contributing too.

As a general rule, code is easier to understand (and therefore review and maintain) if consistent in style, structure, and conventions. Anything you contribute should look like it belongs with the rest of the codebase.
Consistency applies to documentation too. It can be distracting for the reader when documentation uses differing tenses, styles, terminology, etc.

Many projects also use templates and checklists when creating issues and submitting pull requests. Always strive to provide the information and complete the desired tasks.

This isn't being done to be difficult.

Assume positive intentions

Projects ask for information because it helps. They're not asking for it to be difficult.
 
Project maintainers don't want you to waste your time. Also, they want to make the best use of their time. They ask for specific information to evaluate and accept a change or understand an issue. They don't do it to waste your time.

This point goes both ways.
Project maintainers need to remember that when an issue is raised with minimal details, it's not because someone is being difficult or lazy. They may not have been able to provide more information. They may not even speak the same language. 
Be kind.

Explain why. Don't say "should"!

If raising an issue, explain why you want a change, or how a new feature will help you. This helps others understand and allows appropriate prioritization.

Never say, "you should make it do X" without explaining why. 
I'm sure your opinions and ideas are great, but you need to do more than state them.
Is this currently causing you a problem? Or is it just something you think would be a "nice to have"? Why you're asking for or suggesting something can be essential to know.

Focus

And if you're raising issues about problems or suggesting new features, create separate issues for each problem or idea.

Breaking work down into discrete areas can help with understanding, prioritization, and associating changes.

It's much easier to triage and manage work when an issue only lists one problem.
It's easier to review a change that fixes one bug or adds one feature.

It's also useful when discussions remain focused.
Depending on the project, it may or may not be appropriate to have side discussions in issues or comments. I want to be more involved with several open-source projects, but I can't filter out all the seemingly unrelated discussions and so am unable to follow all the relevant discussions that occur.
Follow the conventions of the project regarding side discussions. 

Everything helps

The success of very few projects is predominantly decided by the code. Many other factors play their part, and you can contribute to these too.


This includes writing, expanding, or translating documentation. - There are projects I contribute to where they don't need other people writing code, but I can make a valuable contribution by writing docs.

The same goes for testing. - There are projects where others are paid to write code, but I can come in as an external contributor and make significant, valuable contributions by creating tests.


Again, there are projects where I add value by asking questions.

  • What about people who are using this for the first time?
  • Did you consider X?
  • Why did you do it that way?

This can be informal or as part of a code review.


Bringing different perspectives and experiences helps create something useful to more people and a wider variety of people.


Everything helps.


You can also support projects in other ways. For examples, see https://rapidxaml.dev/support


Financial support can be great if you can provide it, but not every project needs it.

Even if you can't provide a financial contribution, there are ways to support projects you use and value.

  • Leave a star on GitHub.
  • Leave a review or a star rating.
  • Spread the word through a tweet, blog post, stream, video, or whatever you use.


Feedback can be really encouraging for people investing in the creation of open-source projects and is a reminder that their effort is valued and appreciated.


Show you care. Show your support.