Skip to content
SDK Documentation

Contribution Guidelines

Contributions involve many processes to manage the contribution and ensure code quality.

Choose an Issue

  1. Look at the TCSDK project in Jira.

  2. Look for issues listed under Triage without an assignee or explore the backlog for issues. Backlog issues are curated and triaged based on priority.

  3. Select an issue to work on, add yourself as an assignee and add a comment to the issue that:

    • Tags
    • States your interest in the issue

  4. Move the issue to “Selected for Development”.

If the issue does not already exist as a Jira issue, create a ticket in the TCSDK backlog.

How to Correctly Submit a Jira issue

Start by cloning one of these issues:

  • For a story or task, clone TCSDK-20.
  • For a bug, clone TCSDK-21.

Complete the new issue as follows:

  • Associate the issue with the epic “Innersource”.

  • Add at least one of the following components as appropriate for your work:

    • TID-SDK (Trimble Cloud Authentication SDK)
    • DO-SDK (Data Ocean SDK)
    • PF-SDK (Processing Framework SDK)
    • EV-SDK (Events SDK)

  • Add a label corresponding to the language:

    • C#
    • JS
    • Python

  • Enter a clear description of what the issue is about. Provide examples and issue details.

  • Provide a clear, detailed issue title that starts with one of the following tags:

    • [New Feature]
    • [Enhancement]
    • [Bug]
    • [Security]

Add acceptance criteria to describe the required outcome of the issue. Add new acceptance criteria to the top of the existing acceptance criteria in the template.

Once the issue is reviewed by the trusted contributors and the product team based on technical and business aspects, it is moved to “Selected for Development”. After a successful review, you can begin to work on the issue.

If reviewers do not approve your issue, they close it within a week with comments explaining the reasons. Contact individual reviewers or respond in the Jira issue if you need clarification.

Please DO NOT work on any stories unless they are “Selected for Development”.

Code Conventions

Any contribution to the repository should ensure that:

  • Coding conventions and design patterns are in place
  • Code is unit-tested thoroughly
  • Code meets all the acceptance criteria defined in the story
  • Code is optimized and avoids redundancy
  • Code does not break any existing feature
  • Code does not introduce any lint
  • Code is properly and thoroughly commented, particularly for methods that are exposed to consumers

Testing Conventions

Test any contribution so that it satisfies these criteria:

  • Write unit tests to ensure that your code is completely covered.
  • Use existing mocking frameworks to ensure all scenarios are captured.
  • Manually test it against its platform to ensure the correct functionality.
  • Ensure it does not break any existing functionality by performing basic sanity checks.
  • Ensure there are no build failures while submitting pull requests.

After review and build, your contribution then goes through QA testing focuses on compatibility testing amongst various platforms.

Code Review

Trusted committers are responsible for ensuring any PR is reviewed and ensuring the contribution matches all the guidelines defined before approving the PR. Trimble Cloud has a Trimble Cloud SDK team who manages and reviews the PRs. They are added as default reviewers for the repository. Normally the pull request is reviewed within 5 working days.

How to Submit a Pull Request

As you assemble materials for your pull request, ensure that your information is complete:

  • Ensure that your description follows the Pull Request template and includes all of the mandatory fields and any optional fields you need.
  • Include as much information as possible without assuming that reviewers are familiar with your work.
  • Support your implementation with sample apps to demonstrate that the code works as intended.
  • Include screenshots or videos that might help reviewers to understand your pull request.

After submitting a pull request, keep track of the build to ensure that it succeeds. In the event of a build failure due to issues with your code, rescind the pull request, resolve the issues, and submit a new pull request.

Documentation

Upon a successful build, documentation is automatically generated for each environment based on code comments. Please ensure that methods that are exposed to consumers are commented thoroughly.

Build Process

In the continuous integration system, raising a pull request triggers a build, including all dependent modules, to ensure that the code works across all platforms. Generated binaries are uploaded to either Artifactory or the Nuget store, depending on which SDK is being built.