Skip to content
This repository has been archived by the owner on Aug 22, 2024. It is now read-only.

Latest commit

 

History

History
187 lines (130 loc) · 9.96 KB

CONTRIBUTING.md

File metadata and controls

187 lines (130 loc) · 9.96 KB

Contributing to the Azure Kinect SDK

The Azure Kinect SDK team welcomes community feedback and contributions. This repo is relatively new and team members are actively defining and refining the process. Feel free to point out any discrepancies between documented process and the actual process.

Reporting issues and suggesting new features

If the Azure Kinect SDK is not working the way you expect it to, then please report that with a GitHub Issue.

Filing a bug

Please review the list of open Issues to see if one is already open. Please review all categories, Bugs and Enhancements. Also check for closed Issues before opening a new one.

When opening a new issue be sure to document:

  • Steps to reproduce the error
  • Expected results
  • Actual results
  • SDK version
  • Firmware version
  • Log Results from the repro (if possible)

Requesting new features

Please review the list of open Issues to see if one is already open. Please review all categories, Bugs and enhancements. Also check for Closed Issues before opening a new one. If you have a small enhancement that is well defined, please create a new feature request on GitHub.

If you have a larger idea for a new feature please share it with us on Microsoft Azure Feedback Forums where the rest of the community can up vote it too. We will review the submitted ideas very frequently, usually twice weekly.

Below is our list of possible status states we may assign to the request:

Microsoft Azure Feedback Forums status Process steps definition
No status New issue we have not looked at yet
Need Feedback Idea doesn't have enough details or needs more community support
Under Review Proposal for the new feature is created and in review
Planned Approved to get the work started
Started Work started
Completed Feature is released
Declined We have decided not to make this change
Moved Issue which has been moved to GitHub
Archived Feature not possible to implement on current HW.
Triaged Request has been seen and is under internal discussion

No status

This is a new request that we have not yet seen. Within a week we should have reviewed the request and assigned it an initial state.

Needs Feedback

The Azure Kinect team uses this state to ask for more information about this issue. We may need more information from the issue filer as we don't completely understand the request. We might also use this status because we are waiting for more community feedback on the proposal; either in the form of spec feedback or up voting.

Under Review

The team is actively reviewing the proposal and determine what the next actions should be. We may ask for more information, iterate on the proposal, or move to planned state while we wait for resources. We will also need to carefully consider not only the work to implement the request but the work needed to be invested our build and test infrastructure to ensure quality of the code remains high.

Planned

The requested issue has been planned but not yet started. It may stay in this state indefinitely if we don't have resources to complete the request.

Started

Work on the feature, new tests, and possible infrastructure changes have begun.

Completed

The requested issue has been checked into develop branch and we are done. The feature however, may not yet be part of a release.

Declined

We have consider the request and have decided not to implement it due to various reasons. For example, the idea cannot be implemented with the current hardware.

Moved

Issue has been moved to GitHub for tracking.

Archived

We will archive the idea if the current hardware can't support the request.

Triaged

We use the this status to indicate that request has been seen and is under internal discussion.

Finding issues you can help with

Looking for something to work on? Issues marked Good First Issue are a good place to start.

You can also check the Help Wanted tag to find other issues to help with. If you're interested in working on a fix, leave a comment to let everyone know and to help avoid duplicated effort from others.

Once you are committed to fixing an issue, assign it to yourself so others know the issue has an owner.

Contributing code changes

We welcome your contributions, especially to fix bugs and to make improvements which address the top Issues. Some general guidelines:

  • DO create one pull request per Issue, and ensure that the Issue is linked in the pull request.
  • DO follow our Coding and Style guidelines, and keep code changes as small as possible.
  • DO include corresponding tests whenever possible.
  • DO check for additional occurrences of the same problem in other parts of the codebase before submitting your PR.
  • DO link the Issue you are addressing in the pull request.
  • DO write a good description for your pull request. More detail is better. Describe why the change is being made and why you have chosen a particular solution. Describe any manual testing you performed to validate your change.
  • DO NOT submit a PR unless it is linked to an Issue marked Triage Approved. This enables us to have a discussion on the idea before anyone invests time in an implementation.
  • DO NOT merge multiple changes into one PR unless they have the same root cause.
  • DO NOT submit pure formatting/typo changes to code that has not been modified otherwise.

NOTE: Submitting a pull request for an approved Issue is not a guarantee it will be approved. The change must meet our high bar for code quality, architecture, and performance.

Making changes to the code

Building

Check out how to set up your environment and do a build here.

Style Guidelines

The public API surface is written in C. Internally most of the code is C, C++ is used only when necessary, such as when leveraging other open source projects that are written for C++.

Style formatting is enforced as part of check in criteria using .clang-format.

See standards for more information.

Testing

To complete a PR all tests must pass. Please see testing.md for more information.

Workflow for Submitting a Change

Azure Kinect uses the GitHub flow where most development happens on the develop branch. The develop branch should always be in a healthy state.

  1. Start with an issue that has been tagged with Triage Approved. Otherwise, create an Issue and start a conversation with the Azure Kinect Team to get the Issue Triage Approved.
  2. If you have not already, fork the repo.
  3. Make changes.
  4. Test the change, all tests should pass:
    • CTest -L unit
    • CTest -L function
    • CTest -L perf
  5. Create a pull request.
    • The PR description must reference the issue.
  6. An Azure Kinect SDK team member will review the change. See the review process for more information.
    • 1 team member must sign off on the change.
    • Other reviewers are welcome.
  7. After the change has been reviewed by a team member, the PR will be submitted to the Azure Kinect CI system for official build and testing.
    • In the event of a test failure, the PR owner must address and provide a new PR commit and the review process starts over.
  8. Once the change is signed off by a team member and the test pass shows no regressions, an Azure Kinect team member will complete the PR.

NOTE: Any update to the pull request after approval requires additional review and test pass.

When completing a pull request, we will generally squash your changes into a single commit. Please let us know if your pull request needs to be merged as separate commits.

Review Process

After submitting a pull request, members of the Azure Kinect team will review your code. We will assign the request to an appropriate reviewer. Any member of the community may participate in the review, but at least one member of the team will ultimately approve the request.

Often, multiple iterations will be needed to respond to feedback from reviewers. Try looking at past pull requests to see what the experience might be like.

After at least one member of the Azure Kinect team has approved your request, it will be merged by a member of the Azure Kinect team. For Pull Requests where feedback is desired but the change is not complete, please mark the Pull Request as a draft.

Contributor License Agreement

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.