Home

The qiskit.org wiki

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.

Dealing with code

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.

Feature branches

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 master.

When working against a feature branch, you consider the feature branch to be the master 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-header

And 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-branch

Live previews

As 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.

Merging

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 master or a feature branch, the PR should be merged with the Squash and Merge option.

When merging a feature branch against master, its history should be sanitized and merge with Rebase and Merge to preserve all the intermediate commits.

Delayed reviews

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 master 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.

Team best practices

Apply the Scout Rule

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".

Keep the pull request focused

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!

Open follow-ups

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:

1. Once for you to make the change.
2. Another for the reviewer to switch context and review the changes.

Review in layers

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.

1. Start by testing the branch and indicating errors in the implementation.
2. Continue asking for clarifications about what you don't understand.
3. Then, address semantic and architectural problems including type annotations that will result in the hardest-to-remove technical debt in the future.
4. Now, you can focus on readability: typos, variable names, team idioms, style violations not caught by the automated checks.
5. Finally, go for other less critical code smells.

Make branch names meaningful

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

Sanitize your branch history

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.

Project management

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.

Team best practices

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.

Talk soon, talk often

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!

Keep track of compromises

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.

Estimate issues

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.

Split the tasks

Splitting tasks helps in keeping issues small, focused and independent so more people can work in parallel without waiting times.