Table of Contents

Open Sentry Web Site IN-PROGRESS

Contributing

You have found a bug or you have an idea for a cool new feature? Contributing code is a great way to give something back to the open source community. Before you dig right into the code there are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

Getting started

  • Make sure you have a GitHub account[1].
  • Find the corresponding repository on GitHub[2].
  • Submit a GitHub issue in the repository to request a change, assuming one does not already exist.
    • Clearly describe the issue including steps to reproduce when it is a bug.
    • Include screenshots and outputs whenever relevant.
    • If known, explain what should be changed to fix the problem.
    • If possible, specify how to test the new feature.
  • Fork[3] and check out your forked repository.

Making changes

  • Ensure your fork of the repository is up-to-date (use GitHub's fork sync feature[4], and pull to your local clone of the repository).
  • Create a topic branch for your isolated work, named feature/short-description (the name is prefixed with feature/ even if your change fixes a bug).
    • Usually you should base your branch on the main branch.
    • A good topic branch name can be the GitHub issue id (#nnn) plus a short description, e.g. feature/issue-53-fix-https-certificate.
    • If you have submitted multiple JIRA issues, try to maintain separate branches and pull requests.
    • Check our branching model[5] for more details.
  • Make commits of logical units.
    • Make sure your commit messages are meaningful and in the proper format. Your commit message should contain the key of the GitHub issue.
    • Example: Issue #53: Changed the implementation of the keystore
  • Respect the original code style:
    • Only use tabs for indentation.
    • Create minimal diffs – disable On Save actions like Reformat Source Code or Organize Imports. If you feel the source code should be reformatted or refactored somehow, create a separate PR for this change first. Smaller changes are more likely to get approved by reviewers!
  • Make sure you have added the necessary tests for your changes, typically in src/test/java.
  • Run all the tests with mvn clean verify to ensure nothing else was accidentally broken.
  • Build the project site with mvn site and verify the configured code quality reports (in the Project Reports section).

Making trivial changes

Cosmetic or trivial changes in a project, like indentation, white spaces, typos, or minor refactoring don't require creating a dedicated GitHub issue, but they must not be mixed with other significant changes: a separate commit and separate Pull Request must be submitted.

In this case, the topic branch should be named trivial/short-description.

Submitting changes

  • Push your changes to a topic branch in your fork of the repository.
  • Submit a Pull Request (PR) to the corresponding repository in the sentrysoftware organization.
    • Verify Files Changed shows only your intended changes and does not include additional files or changes like white spaces, etc.
    • Make sure all automatic checks are successful.
    • Verify comments produced automatically by code quality automatic checks.
  • When implementing additional changes after reviewers suggestions, simply commit and push such changes. Never squash or rebase commits that you have already pushed!
  • Once your PR is merged (if approved), sync your forked repository[4], pull these changes to your locally cloned repository and delete your branch.

Builds

To facilitate external contributions, automatic builds don't happen on Sentry Software's internal Jenkins server, but directly in GitHub with GitHub Actions[6].

Whenever possible, Sentry Software open-source projects must use shared workflows from the sentrysoftware/workflows[7] repository to build, deploy artifacts, and release new versions.

Java libraries

Sentry Software's open-source Java library projects are published on Maven Central. We will enforce several requirements to ensure the quality of our libraries:

  • The project must publish its Maven Site (mvn site) with full reports as GitHub Pages:
  • Maven's artifact groupId must be org.sentrysoftware.*
  • License must be Apache-2.0[12] and all source files must include a header with the Apache-2.0 notice. We use mvn license:update-file-header to update the source file headers.
  • Publish the Javadoc and Source artifacts along with the main artifact

Pull Requests will trigger the maven-build.yml[13] GitHub Action workflow to make sure the project builds.

SNAPSHOT artifacts will be deployed automatically to the Maven Central Snapshot repository[14] on changes on the main branch with the maven-central-deploy.yml[15] GitHub Action workflow.

Releases are performed with the maven-central-release.yml[16] GitHub Action workflow, which deploys the artifacts in a staging repository on Maven Central[17]. The staging repository must be released manually once validated by the testing team, which makes the artifact available on Maven Central for good. Login to https://s01.oss.sonatype.org/[18] to release the staging repository.

Happy coding! 😊

Additional resources

contributor open source oss
Links:
  • [1] https://github.com/join
  • [2] repos.html
  • [3] https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
  • [4] https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork
  • [5] branching.html
  • [6] https://docs.github.com/en/actions/quickstart
  • [7] https://github.com/sentrysoftware/workflows
  • [8] https://checkstyle.org/
  • [9] https://docs.pmd-code.org/latest/pmd_userdocs_cpd.html
  • [10] https://pmd.github.io/
  • [11] https://spotbugs.github.io/
  • [12] https://www.apache.org/licenses/LICENSE-2.0
  • [13] https://github.com/sentrysoftware/workflows/blob/main/.github/workflows/maven-build.yml
  • [14] https://s01.oss.sonatype.org/content/repositories/snapshots/
  • [15] https://github.com/sentrysoftware/workflows/blob/main/.github/workflows/maven-central-deploy.yml
  • [16] https://github.com/sentrysoftware/workflows/blob/main/.github/workflows/maven-central-release.yml
  • [17] https://s01.oss.sonatype.org/content/groups/staging
  • [18] https://s01.oss.sonatype.org/
  • [19] https://github.com/sentrysoftware/oss-maven-template
  • [20] https://help.github.com/
  • [21] https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
No results.