Roles#

pandas uses two levels of permissions:triage andcore team members.

Triage members can label and close issues and pull requests.

Core team members can label and close issues and pull request, and can mergepull requests.

GitHub publishes the fulllist of permissions.

Tasks#

pandas is largely a volunteer project, so these tasks shouldn’t be read as“expectations” of triage and maintainers. Rather, they’re general descriptionsof what it means to be a maintainer.

• Triage newly filed issues (seeIssue triage)

• Review newly opened pull requests

• Respond to updates on existing issues and pull requests

• Drive discussion and decisions on stalled issues and pull requests

• Provide experience / wisdom on API design questions to ensure consistency and maintainability

• Project organization (run / attend developer meetings, represent pandas)

https://matthewrocklin.com/blog/2019/05/18/maintainer may be interesting backgroundreading.

Issue triage#

Triage is an important first step in addressing issues reported by the community, and evenpartial contributions are a great way to help maintain pandas. Only remove the “Needs Triage”tag once all of the steps below have been completed.

Here’s a typical workflow for triaging a newly opened issue.

1. Thank the reporter for opening an issue

   The issue tracker is many people’s first interaction with the pandas project itself,beyond just using the library. As such, we want it to be a welcoming, pleasantexperience.

2. Is the necessary information provided?

   Ideally reporters would fill out the issue template, but many don’t.If crucial information (like the version of pandas they used), is missingfeel free to ask for that and label the issue with “Needs info”. Thereport should follow the guidelines inBug reports and enhancement requests.You may want to link to that if they didn’t follow the template.

   Make sure that the title accurately reflects the issue. Edit it yourselfif it’s not clear.

3. Is this a duplicate issue?

   We have many open issues. If a new issue is clearly a duplicate, label thenew issue as “Duplicate” and close the issue with a link to the original issue.Make sure to still thank the reporter, and encourage them to chime in on theoriginal issue, and perhaps try to fix it.

   If the new issue provides relevant information, such as a better or slightlydifferent example, add it to the original issue as a comment or an edit tothe original post.

4. Is the issue minimal and reproducible?

   For bug reports, we ask that the reporter provide a minimal reproducibleexample. Seehttps://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reportsfor a good explanation. If the example is not reproducible, or if it’sclearly not minimal, feel free to ask the reporter if they can providean example or simplify the provided one. Do acknowledge that writingminimal reproducible examples is hard work. If the reporter is struggling,you can try to write one yourself and we’ll edit the original post to include it.

   If a reproducible example can’t be provided, add the “Needs info” label.

   If a reproducible example is provided, but you see a simplification,edit the original post with your simpler reproducible example.

   If this is a regression report, post the result of agitbisect run.More info on this can be found in theInvestigating regressions section.

   Ensure the issue exists on the main branch and that it has the “Needs Triage” taguntil all steps have been completed. Add a comment to the issue once you haveverified it exists on the main branch, so others know it has been confirmed.

5. Is this a clearly defined feature request?

   Generally, pandas prefers to discuss and design new features in issues, beforea pull request is made. Encourage the submitter to include a proposed APIfor the new feature. Having them write a full docstring is a good way topin down specifics.

   Tag new feature requests with “Needs Discussion”, as we’ll need a discussionfrom several pandas maintainers before deciding whether the proposal is inscope for pandas.

6. Is this a usage question?

   We prefer that usage questions are asked on StackOverflow with the pandastag.https://stackoverflow.com/questions/tagged/pandas

   If it’s easy to answer, feel free to link to the relevant documentation section,let them know that in the future this kind of question should be onStackOverflow, and close the issue.

7. What labels and milestones should I add?

   Apply the relevant labels. This is a bit of an art, and comes with experience.Look at similar issues to get a feel for how things are labeled.

   If the issue is clearly defined and the fix seems relatively straightforward,label the issue as “Good first issue”.

   If the issue is a regression report, add the “Regression” label and the next patchrelease milestone.

   Once you have completed the above, make sure to remove the “Needs Triage” label.

Investigating regressions#

Regressions are bugs that unintentionally break previously working code. The common wayto investigate regressions is by usinggit bisect,which finds the first commit that introduced the bug.

For example: a user reports thatpd.Series([1,1]).sum() returns3in pandas version1.5.0 while in version1.4.0 it returned2. To begin,create a filet.py in your pandas directory, which contains

importpandasaspdassertpd.Series([1,1]).sum()==2

and then run:

gitbisectstartgitbisectgoodv1.4.0gitbisectbadv1.5.0gitbisectrunbash-c"python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true; python t.py"

This finds the first commit that changed the behavior. The C extensions have to berebuilt at every step, so the search can take a while.

Exit bisect and rebuild the current version:

gitbisectresetpython-mpipinstall-ve.--no-build-isolation-Ceditable-verbose=true

Report your findings under the corresponding issue and ping the commit author to gettheir input.

Closing issues#

Be delicate here: many people interpret closing an issue as us saying that theconversation is over. It’s typically best to give the reporter some time torespond or self-close their issue if it’s determined that the behavior is not a bug,or the feature is out of scope. Sometimes reporters just go away though, andwe’ll close the issue after the conversation has died.If you think an issue should be closed but are not completely sure, please applythe “closing candidate” label and wait for other maintainers to take a look.

Reviewing pull requests#

Anybody can review a pull request: regular contributors, triagers, or core-teammembers. But only core-team members can merge pull requests when they’re ready.

Here are some things to check when reviewing a pull request.

• Tests should be in a sensible location: in the same file as closely related tests.

• New public APIs should be included somewhere indoc/source/reference/.

• New / changed API should use theversionadded orversionchanged directives in the docstring.

• User-facing changes should have a whatsnew in the appropriate file.

• Regression tests should reference the original GitHub issue number like#GH-1234.

• The pull request should be labeled and assigned the appropriate milestone (the next patch releasefor regression fixes and small bug fixes, the next minor milestone otherwise)

• Changes should comply with ourVersion policy.

Backporting#

pandas supports point releases (e.g.1.4.3) that aim to:

1. Fix bugs in new features introduced in the first minor version release.

   • e.g. If a new feature was added in1.4 and contains a bug, a fix can be applied in1.4.3

2. Fix bugs that used to work in a few minor releases prior. There should be agreement between core team members that a backport is appropriate.

   • e.g. If a feature worked in1.2 and stopped working since1.3, a fix can be applied in1.4.3.

Since pandas minor releases are based on GitHub branches (e.g. point release of1.4 are based off the1.4.x branch),“backporting” means merging a pull request fix to themain branch and correct minor branch associated with the next point release.

By default, if a pull request is assigned to the next point release milestone within the GitHub interface,the backporting process should happen automatically by the@meeseeksdev bot once the pull request is merged.A new pull request will be made backporting the pull request to the correct version branch.Sometimes due to merge conflicts, a manual pull request will need to be made addressing the code conflict.

If the bot does not automatically start the backporting process, you can also write a GitHub comment in the merged pull requestto trigger the backport:

@meeseeksdevbackportversion-branch

This will trigger a workflow which will backport a given change to a branch(e.g. @meeseeksdev backport 1.4.x)

Cleaning up old issues#

Every open issue in pandas has a cost. Open issues make finding duplicates harder,and can make it harder to know what needs to be done in pandas. That said, closingissues isn’t a goal on its own. Our goal is to make pandas the best it can be,and that’s best done by ensuring that the quality of our open issues is high.

Occasionally, bugs are fixed but the issue isn’t linked to in the Pull Request.In these cases, comment that “This has been fixed, but could use a test.” andlabel the issue as “Good First Issue” and “Needs Test”.

If an older issue doesn’t follow our issue template, edit the original post toinclude a minimal example, the actual output, and the expected output. Uniformityin issue reports is valuable.

If an older issue lacks a reproducible example, label it as “Needs Info” andask them to provide one (or write one yourself if possible). If one isn’tprovide reasonably soon, close it according to the policies inClosing issues.

Cleaning up old pull requests#

Occasionally, contributors are unable to finish off a pull request.If some time has passed (two weeks, say) since the last review requesting changes,gently ask if they’re still interested in working on this. If another two weeks orso passes with no response, thank them for their work and then either:

• close the pull request;

• push to the contributor’s branch to push their work over the finish line (ifyou’re part ofpandas-core). This can be helpful for pushing an important PRacross the line, or for fixing a small merge conflict.

If closing the pull request, then please comment on the original issue that“There’s a stalled PR at #1234 that may be helpful.”, and perhaps label the issueas “Good first issue” if the PR was relatively close to being accepted.

Becoming a pandas maintainer#

The full process is outlined in ourgovernance documents. In summary,we’re happy to give triage permissions to anyone who shows interest bybeing helpful on the issue tracker.

The required steps for adding a maintainer are:

1. Contact the contributor and ask their interest to join.

2. Add the contributor to the appropriateGitHub Team if accepted the invitation.

   • pandas-core is for core team members

   • pandas-triage is for pandas triage members

If adding topandas-core, there are two additional steps:

3. Add the contributor to the pandas Google group.

4. Create a pull request to add the contributor’s GitHub handle topandas-dev/pandas/web/pandas/config.yml.

The current list of core-team members is atpandas-dev/pandas

Merging pull requests#

Only core team members can merge pull requests. We have a few guidelines.

1. You should typically not self-merge your own pull requests without approval.Exceptions include things like small changes to fix CI(e.g. pinning a package version). Self-merging with approval from othercore team members is fine if the change is something you’re very confidentabout.

2. You should not merge pull requests that have an active discussion, or pullrequests that has any-1 votes from a core maintainer. pandas operatesby consensus.

3. For larger changes, it’s good to have a +1 from at least two core team members.

In addition to the items listed inClosing issues, you should verifythat the pull request is assigned the correct milestone.

Pull requests merged with a patch-release milestone will typically be backportedby our bot. Verify that the bot noticed the merge (it will leave a comment withina minute typically). If a manual backport is needed please do that, and removethe “Needs backport” label once you’ve done it manually. If you forget to assigna milestone before tagging, you can request the bot to backport it with:

@Meeseeksdev backport <branch>

Release process#

The release process makes a snapshot of pandas (a git commit) available to users witha particular version number. After the release the new pandas version will be availablein the next places:

• Git repo with anew tag

• Source distribution in aGitHub release

• Pip packages in thePyPI

• Conda packages inconda-forge

The process for releasing a new version of pandas is detailed next section.

The instructions contain<version> which needs to be replaced with the versionto be released (e.g.1.5.2). Also the branch to be released<branch>, whichdepends on whether the version being released is the release candidate of a new version,or any other version. Release candidates are released frommain, while otherversions are released from their branch (e.g.1.5.x).