-
Notifications
You must be signed in to change notification settings - Fork 108
Home
Welcome to the qiskit.org wiki! Most of the content here is for core contributors. However, be you an internal or external contributor, make sure you read the contribution guidelines. There you will find general information about contributing to qiskit.org and other IBM Community Digital efforts.
When you finish reading the contribution guidelines, you can return here to learn more about core contributor procedures.
Core contributors of qiskit.org team up with other core developers and become responsible of the health of the code base. Here you will find the specifics of the collaboration procedures we follow.
Very often, implementing a user story implies publishing several features in an atomic
batch. When it happens, we use a feature branch in the main repository for integrating
all the needed changes before merging to main.
When working against a feature branch, you consider the feature branch to be the
main branch and so, when about to start a new task, you do:
git checkout feature-branch
git pull upstream feature-branch
git checkout -b issue-1234-new-headerAnd keep an eye on feature-branch to always rebase your code on top of the most
updated version of the feature-branch:
git checkout feature-branch
git pull upstream feature-branch
git checkout issue-1234-new-header
git rebase -i feature-branchAs part of our continuous integration infrastructure, every pull request receives a dedicated URL by Vercel to preview the changes in it.
When the contribution comes from an external contributor, previews require authorization from one of the core members of the team.
Once all automated checks are passing and there is a positive review, the pull request can be merged. It does not matter if it is the author or the reviewer who merges the PR.
When merging a regular pull request against main or a feature branch, the PR should
be merged with the
Squash and Merge
option.
When merging a feature branch against main, its history should be sanitized and
merge with Rebase and Merge to preserve all the intermediate commits.
A delayed code review is a code review that happens after the PR is merged. It is intended to reduce waiting times for implementers and maximize short-term productivity at the expense of fixing technical debt by the end of the sprint.
They can only happen when the pull request is created against a feature branch. The delayed code
review is required to be addressed in the same sprint, and a final review of the feature branch is
required before merging. No code can be merged into main without revision.
Delayed reviews can only happen for pull requests authored by core members of the team and the strategy needs to be agreed in advance.
Leave the code better than you found it... in the context of what you're addressing.
Boy Scouts have a rule that says: "Always leave the campground cleaner than you found it", which does not mean, "leave the whole forest cleaner than you found it".
A pull request should solve only one thing. This makes it easier to review and share, reduce risk and criticality and improve understanding of the changes. If you find yourself in a position of doing more than needed, even if this is something trivial but not directly related to your current work, come back later! Open a new issue and come back later to address that problem. Follow-ups are welcome!
We know it. It is hard just to ignore that something else can be improved. Don't do it.
When you foresee that addressing a problem will take more effort than documenting it, choose the latter and open a follow-up. When assessing the effort, think twice:
- Once for you to make the change.
- Another for the reviewer to switch context and review the changes.
When reviewing, highlighting all the things that you consider can be improved may be exhausting for the contributor. Instead of noticing everything at the same time, try to layer your review.
- Start by testing the branch and indicating errors in the implementation.
- Continue asking for clarifications about what you don't understand.
- Then, address semantic and architectural problems including type annotations that will result in the hardest-to-remove technical debt in the future.
- Now, you can focus on readability: typos, variable names, team idioms, style violations not caught by the automated checks.
- Finally, go for other less critical code smells.
Include your initials, the number of the issue or both. That helps to identify who started the branch and what issue is being addressed:
sp-issue-1234-implement-new-header
Rebase on your own history to reorder, fix and squash your history. Remember that each commit should represent a meaningful atomic change. For instance, if you commit a new functionality just to realize it is broken because you misspelt a variable, add another commit for fixing it, then rebase and combine both commits together.
In Qiskit, we take open-source seriously and want to be open and transparent to our community. This is why we keep most of our management public, with the help of projects for sprint planning and issues for tracking what needs to be done.
We use a customized version of scrum with 2-weeks sprints and online dailies:
| What? | Why? | When? | Where? |
|---|---|---|---|
| Sprint planning | To plan for the next 2 weeks | Every other Monday from 10.30 am to 11.30 am EST | Leron's WebEx room |
| Sprint review | To present the work of the sprint in front of the stakeholders | Every other Friday from 10.00 am to 11.00 am EST | Leron's WebEx room |
| Sprint retrospective | To review and improve our processes | Every other Friday from 11.00 am to 11.45 am EST | Salva's WebEx room |
| Dailies | To plan for the day and keep the team aware about our work | All days at 10.00 am EST | In qiskit-digital Slack |
A regular sprint looks like follows: the backlog gets populated and prioritized with user stories before the sprint planning. During sprint planning, we split, describe and estimate the work to be done. We work on resolving the tasks for two weeks and, during the sprint review, we demo the work we've been doing. We use retrospective to improve our procedures and start over.
The sprint backlog is the tool the team uses for coordinating and inspecting the progress of the project.
Core-contributors own the sprint backlog which means they are free to manage the tasks on it the way they consider best. It also means they are responsible for keeping it in good shape. That means, among others:
- Assigning to themselves when starting to work on an issue.
- Moving the tasks between columns to reflect their actual status.
- Removing themselves from the list of assignees if they decide to stop working on an issue.
- Sizing.
- Splitting.
We are a global team! Our team is spread through Europe and the US. Remote-working implies we need to be flexible with our schedules and mindful about our team-mates working times. It pays off by enabling us to deliver value for almost 24 hours a day.
We are an agile team, so we value individuals and interactions over processes and tools so, please, use the common Slack channels for sharing important information about the development of the sprint.
Working in a global team imposes new communication challenges. If the information is not shared, part of the team can (in words of @techtolentino) go to sleep fully aligned and awake completely misaligned!
Development is a matter of assuming trade-offs. There will be sprints when we focus on quality to reduce technical debt, there will be sprints when we focus on speed to meet a deadline and there will be sprints when we balance quality and speed.
This also applies to your day-to-day. While you work on fixing issues, you will need to make decisions. Some solutions will seem better than others, and you will make compromises... Track them!
If you are delaying work, create a follow-up, if you find unnoted technical debt, open an issue and make it visible, if you got stuck in a discussion, open a discussion issue and ask for participation.
Estimating issues enables the team to known their limits, prepare for the future and balance the technical effort with the sprint size and project deadlines. We use a simple scale based more in some shared intuition rather than specific definitions but if you are new to the team, we hope this will help you:
| Effort | Time scale |
|---|---|
| Small | Hour scale |
| Medium | Day scale |
| Large | Week scale |
| Extra large | Sprint scale |
Estimation does not include the time of implementation only, it must take the time of review into consideration too. The whole team agrees on the size of a task which implies both, implementer and reviewer of the task, need to make implementation and review fit in the effort agreed.
Splitting tasks helps in keeping issues small, focused and independent so more people can work in parallel without waiting times.
Splitting also has the advantage of enabling faster value delivering. There are tasks that do not require to be finished exhaustively before being ready for merging. Consider splitting them into a smaller task with the big part of the changes and a follow-up for polishing.
Be responsible when splitting tasks. Splitting is not for getting rid of work needed to be done but for merging. If you plan for a big task to be done in a sprint, split and leave both in the sprint. There will be someone else that can take one leveraging parallel work or it will give you the opportunity of switching to a more important task before coming back to the follow-up.