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 for the codebase's health. 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 main.

When working against a feature branch, you should consider the feature branch behaves as main 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 it:

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 pass and there is a positive review, a core developer can merge the pull request. 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, you should sanitize its history 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 developer can merge no code 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 upon 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 to ignore that you can improve something else. Please 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 to realize it is broken because you misspelled a variable, add another commit for fixing it, then rebase and combine both commits.

Deployment

The qiskit.org application uses GitHub Actions to automate releases. This enables us to establish a Workflow and specify various steps that we need to include in our build process.

In the current configuration, the build and deploy Workflow is initiated by the following events:

• a manual trigger of the build
• a push to the main branch (merge)
• triggered automatically, as a part of a scheduled cron job (runs daily at 08:00am UTC)

This build and deploy process includes the following steps:

• checks out project repo
• installs dependencies
• generates assets
• deploys to IBM Cloud Object Storage

It's important to note that the Deploy step, which deploys the generated project assets to IBM Cloud Storage, is part of a larger process that involves other repositories as well. For security/privacy purposes, that larger process is available in an internal, private repository here. Lastly, the secrets used for deploying are maintained by a joint effort between infrastructure team (for qiskit.org).

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-week sprints and online dailies:

What?	Why?	When?	Where?
Dev Backlog Discussion	To review backlog, prior to Sprint planning	Every other Tuesday from 9.30 am to 10.30 am EST	Randy's WebEx room
Sprint planning	To plan for the next 2 weeks	Every other Tuesday 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 Monday from 10.30 am to 11.30 am EST	Leron's WebEx room
Sprint retrospective	To review and improve our processes	Every other Friday from 10.00 am to 10.45 am EST	Salva's WebEx room
Dailies	To plan for the day and keep the team aware of our work	All days around 10.00 am (your timezone)	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 retrospectives to improve our procedures and start over.

Priorities

The product owner is responsible for reviewing and setting new priorities at the beginning of the sprint planning. The development team is then responsible for advancing those during the sprint. code-quality-labeled issues are usually a second priority although we have mechanisms for improving code quality from sprint to sprint and special "refactor sprints" to focus on quality only. During refactor sprints, code-quality issues are the main priority.

Sprint backlog management

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 their tasks 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.

The dev-quality sprint

A.k.a "the refactor sprint".

Development experience has an impact on user satisfaction and product life-cycle. A suboptimal development experience means less maintainable code which increases the difficulty of developing new features, or improving and fixing current ones. The team always produces production-ready code. However, we are conscious that the sprint dynamics such as deadlines, re-prioritization, sudden course changes can have an impact on code quality.

It is the responsibility of the dev team to stop working on user stories and ask (and plan) a "dev-quality" sprint. During this sprint, the product owner is no longer responsible for setting the priorities. The dev team is now the one responsible for prioritizing and working on those things that would enable them to work comfortably again.

It is the perfect time for some code refactors, increasing test coverage, fixing delayed bugs, correcting typos, improving documentation, updating the architecture diagrams, polishing designs, updating the brand book, or switching to a new framework...

Dev-quality sprints are sprints with the goal of reducing technical debt.

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!

It also requires fluid and trusted conversations so get to know your teammates, build a professional rapport based on mutual confidence, respect, and appreciation. Provide both encouraging and corrective feedback, be relevant and timely.

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 delay 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 know 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 on 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 consider the time of review. 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.

Splitting also has the advantage of enabling faster value delivering. Some tasks 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 polishing follow-up.

Be responsible when splitting tasks. Splitting is not for getting rid of work that 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.

Always increase dev-quality

The team always produces production-ready code. That's the regular thing. However, the process of producing new code is not a perfect one and technical debt generated and accumulates through the process. In every sprint, try to always solve a code-quality issue. Choose the easiest ones with the biggest impact and use "refactor sprints" to get rid of big chunks of technical debt.

Dev Backlog Discussion

As part of the the development team's best practices, we meet at the start of each sprint, prior to our team planning session. This allows the developers to review the backlog, discuss task splitting, size stories, and identify opportunities for clarification.