Sprint Guide

What is a sprint?

A sprint is an unstructured opportunity to spend a few hours or days working collaboratively on an Open Source project. They're often tied to a conference; a sprint after a conference provides an opportunity to turn the energy, enthusiasm and interest that a conference has generated into improvements in the software we use on a daily basis.

Sprints are also an opportunity to introduce people to the process of contributing to the project. Our hope is that you'll have so much fun contributing during the sprint that you'll go home and keep contributing!

It doesn't matter how much experience you've got. At past sprints, we've merged contributions from people at all levels of experience - high-school students, recent bootcamp graduates, people who don't consider themselves programmers, and seasoned developers. No matter your experience level - we can find a way for you to contribute.

Code isn't the only way you can contribute, either. A project like BeeWare is much more than just the code - we need people to write, proof-read and translate documentation; we need people to improve the design of web pages; even the process of going through bugs that were reported years ago and determining that they've been fixed along the way is a valuable contribution.

The Initial Questions

To get you started, we're going to ask a few questions so we can gauge your interests and experience. This will help us find the best way for you to contribute. Work through the questions, take notes, and then find a member of the Bee Team and share your answers. If you don't understand the question being asked - don't worry about that! Let us know what you do know, and we'll work together to figure it out from there.

1. Have you used BeeWare before?

   If you haven't, start by working through the BeeWare Tutorial. It will give you an introduction for what the BeeWare project is, and how the pieces of the project fit together. If you hit any problems doing the tutorial, take notes - because ensuring nobody else has the same problem is a great topic for a first contribution!

   Once you've finished the tutorial up to at least step 4, move on to the next question.

2. What computing equipment do you have with you?

   The equipment you have with you puts practical limits on what you can contribute to. For example, if you have a Windows laptop, you're not going to be able to work on anything to do with iOS. Does your laptop run Windows, macOS, Linux, or something else? Is your phone an iOS or Android device? Have your devices been provided by your employer, or are they your own personal devices?

3. How much experience do you have writing Python code?

   Are you new to programming? A Python veteran? A coding veteran who has only just started learning Python? A fresh graduate of a bootcamp program? We want to find a problem that is a good match for your level experience.

4. Are you familiar with Github contribution processes?

   Do you use GitHub (or a similar code-sharing site) for hosting your own code or contributing to others' projects? Do you know what CI (continuous integration) is? Have you contributed to a project that has pre-commit hooks? If I asked you to "rebase your PR against main", would you know what to do?

5. Have you contributed to an Open Source project before?

   Have you attended a sprint in the past? Have you ever submitted a PR (pull request) to an Open Source project? Are you familiar with how to use Github to create a pull request?

6. Do you have any other special skills that might be useful?

   Are you familiar with a GUI API (such as Winforms, Cocoa, or GTK)? Do you have deep knowledge of the internals of a particular operating system? Are you an expert in a programming language other than Python? If you don't have any special skills, that's not a problem - but if we've got a Windows Guru on our hands, we want to make sure those skills are being put to good use.

7. Why did you join us and what are you interested in?

   "You sounded like a friendly project" is a perfectly fine answer. However, if there's more to why you joined us today, let us know. Are you interested in mobile or desktop development? Packaging? Websites? Console apps? If you don't have a specific interest - what seems most interesting based on what you've seen about BeeWare so far?

Now, find a member of the Bee Team to share your answers. They might ask some follow up questions; but then they'll point you in the direction of a area where you should be able to make a contribution.

Find Your Issue

If you've spoken to a member of the Bee Team, they have probably pointed you at a part of the BeeWare project where you can contribute; they might have even suggested a specific issue to work on. If they haven't given you as specific issue, they've probably pointed you at the "Good First Issues" for that project. What does that mean?

GitHub provides a list of issues that allows BeeWare (and other projects) to keep track of all the problems that have been reported - that includes explicit bugs, unexpected behavior that might be a bug, requests for new features, requests for more documentation - anything that might be a way that BeeWare could be improved. As new issues are reported, the Bee Team will flag some of them as issues that are well suited to a first time contributor - issues that don't demand an immediate fix, but are well defined or easy to reproduce, and probably have a good lead on the underlying cause. These issues are tagged "good first issue" to make them easier to find.

To filter a GitHub issue list by the "good first issue" label, follow these steps:

1. Click on the "Labels" button above the list of issues to activate the drop-down menu.
2. Type the word "good" into the search box at the top of the drop-down menu.
3. Click on "good first issue" in the filtered list.

Filtering GitHub issues by the "good first issue" label.

Once you've found an issue that looks interesting, read through any comments on the post, and post a comment in the discussion saying that you're looking into the issue (e.g., "Looking into this at the PyCon US 2025 sprints"). BeeWare doesn't explicitly "assign" issues - we accept contributions from anyone. However, in a sprint situation, we need to make sure that we don't end up with two people working on the same issue - leaving a comment is a light-weight way to coordinate between contributors.

If you still can't find anything you'd like to do, find a Bee Team member and they'll help you narrow down to a specific issue.

Set up a development environment

Once you've found an issue, you'll need to set up your development environment so you can work on a fix. Each BeeWare project has it's own contribution guide:

• Briefcase
• Toga
• Rubicon ObjC

If the project isn't on this list, check the project README for details on how to get set up. If any of the instructions don't make sense (or you can't find those instructions), find a member of the Bee Team, and they'll get you unstuck. And - if you think you can improve the instructions so other people won't hit the same problem, improving the contribution guide is a valuable contribution!

Now you can start working on your issue!

What happens after I submit my PR?

Once you've submitted your pull request, and the pull request is passing all the automated checks, you're ready for a review. Let one of the core team know that you've got a PR ready for review, and they'll take a look.

If this is your first PR, it's quite likely the review will find some problems. That might be an edge case you didn't consider, or a code convention that you haven't followed. Don't be discouraged! Nobody - not even the core team - gets PRs 100% correct on the first try.

Once the PR passes review, your reviewer will merge the PR - and you're done! Congratulations - you've contributed to BeeWare! If this is your very first BeeWare contribution, you've also earned your BeeWare Challenge Coin - find a member of the core team, and they will give you a coin!

Help! I'm stuck!

If you get stuck at any point along the way, find a member of the Bee Team. Don't be afraid to ask any question. If you're stuck, we want to get you unstuck. If you're confused, it's because the topic is complicated, and we haven't explained it well enough. We're eager to help - and we want to make sure you have a successful sprint.