Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
264 lines (187 loc) · 14.9 KB

CONTRIBUTING.md

File metadata and controls

264 lines (187 loc) · 14.9 KB

Contributing to HPCToolkit

All types of contributions are valued. See the list below for instructions and information about different ways to contribute. Please make sure to read the relevant section and any linked information in their entirety before making your contribution, it makes it at lot easier for us maintainers and smooths out the experience for everyone involved.

This project and everyone participating in it are governed by the Linux Foundation Projects Code of Conduct. By participating, you are expected to uphold this code.

We look forward to your involvement as a Contributor to the HPCToolkit Project.

I have a question!

We're happy to answer! But before you ask, we ask that you:

  1. Read through the documentation. The answer may be there, even if it's not very obvious. If it's confusing, feel free to contribute an improvement to the documentation to make it easier for others.

  2. Search our issue tracker on GitLab. There may be another issue that may help your query. If you do find one, feel free to leave a 👍 and/or a helpful comment to show your interest. Be sure to check for both open and closed issues.

  3. Read or search the documentation from your sysadmins or for any involved tools/applications. There may be details that are causing your confusion.

If you are still confused or have unanswered questions, feel free to open an issue. Once your question is answered, we may ask you to contribute an update the documentation for others.

I want to report a bug!

Something not working right? Before filing a bug, we ask that you:

  1. Confirm you are running the latest released or development version of HPCToolkit. Given the project's limited manpower, we don't prioritize support of older releases.

  2. Read any documentation from your sysadmins and ensure your environment is sane. Examples include loading incompatible modules from different authors, failing to set LD_LIBRARY_PATH, force-loading library dependencies incompatible with your build of HPCToolkit, etc.

  3. Read through the documentation. If the bug is intended behavior, consider asking a question about it or suggesting an enhancement to change it first.

  4. Search our issue tracker on GitLab for problems similar to yours. If you find one, please add a 👍 and/or a comment with your particular build parameters. Be sure to check both open and closed issues.

If you are still seeing unexpected behavior, please open a new issue and follow the tips & tricks below.

Tips and tricks for writing a good bug report

  1. Check if the issue still exists in the latest development version of HPCToolkit. This can be installed with Spack via:

    $ spack uninstall -a hpctoolkit@develop
$ spack install hpctoolkit@develop [+features...]

    See the README.md for additional install options and instructions.

  2. Provide any relevant context. Your OS, distribution, CPU architecture and versions of related dependencies are helpful (e.g. Ubuntu 22.04 x86-64, CUDA 12.5). Your hostname, shell, loaded modules or sysadmin's email address are not.

  3. Try to reduce your example to the minimum reproducer and steps needed to trigger the issue. We cannot efficiently help if we don't have a way to easily recreate the failing scenario. Please avoid external code (e.g. git clone my.cool/project) so that we can adapt your reproducer into a regression test.

  4. Give details for what happened that you didn't expect. If the output is unexpected, show the erroneous output and explain why you are certain it is wrong. If a tool crashed, provide a stack trace from gdb.

  5. Upload any relevant log output you have. hpcrun generates *.log files in the output directory. hpcstruct and hpcprof produce logs on stdout/stderr.

  6. Wait patiently for a response. It may take a while before we can get back to you.

Suggesting an enhancement or feature

Need some extra features for HPCToolkit to work for you? Before you make a request, we ask that you:

  1. Read through the documentation. We may already have the feature in a different form than you were initially expecting.

  2. Search our issue tracker on GitLab for requests for the same or similar features. If you find someone with the same use case, add a 👍 and/or a supportive comment to show your interest.

If you can't find any similar feature requests, feel free to open a new issue and follow the tips & tricks below.

Tips and tricks for writing a good feature request

  1. Describe your use case / scenario in detail and how it applies to the community of users. We want to support the use cases of many users, including you.

  2. Avoid XY problems. Start by describing the use case (Y) instead of how you intend to solve it (X).

  3. Explain how your proposed feature solves your use case. The worst outcome is that your feature gets implemented and it doesn't solve the original problem.

  4. If possible, include a workaround that more-or-less achieves the main goal with no HPCToolkit changes. This helps other users get their work done without having to wait for the feature to be implemented.

  5. Be open to alternative solutions that satisfy your use case. There are always multiple solutions to the same problem.

  6. Wait a little before trying to implement your feature yourself. There may be design or other high-level issues that may drastically change how the code is implemented.

    [!note] However, if you do implement it yourself, we ask that you assign yourself to the issue and contribute your changes back to HPCToolkit.

Contributing Changes

Thanks for your efforts to improve HPCToolkit, and welcome to the community of Contributors to the HPCToolkit Project! There's a few things to keep in mind before and while contributing your changes, please read the sections below for details.

The Legal Stuff

  1. We require that all technical changes are made under the Apache License 2.0 or under the MIT license. Documentation changes must be under the Creative Commons Attribution 4.0. Data must be under the CDLA-Permissive 2.0 license.

  2. The copyright and license must be specified by headers compatible with the REUSE Specification. In most cases this is in a comment at the top of the file, for example:

    // SPDX-FileCopyrightText: Contributors to the HPCToolkit Project
//
// SPDX-License-Identifier: Apache-2.0

    [!important] If you're editing an existing file, it may be that the licensing annotations at the top of the file don't quite match the license for your contribution. This is especially true if your contribution contains code copied from another project. If your change is fairly self-contained, you should consider separating your new code as a "snippet" with its own REUSE headers:

    // SPDX-SnippetBegin
// SPDX-FileCopyrightText: Contributors to the HPCToolkit Project
// SPDX-License-Identifier: Apache-2.0

// ... your code here ...

// SPDX-SnippetEnd

  3. Copyrights should be made out to "Contributors to the HPCToolkit Project," meaning you! We do not require that you hand over your copyright rights to contribute.

  4. We require that all technical contributions to HPCToolkit are accompanied with a Developer Certificate of Origin sign-off in every Git commit message. You can pass the -s/--signoff flag to git commit to generate this trailer, for example:

    Signed-off-by: Thomas Jefferson <thomas.jefferson@president.gov>

    [!tip] If your commits are missing this, you can edit the commit message and add the trailer with git commit --amend -s.
    For many commits, try:

    git rebase -x 'git commit --amend -s --no-edit' develop

  5. Read over the LICENSE for information about how your contribution will be licensed when distributed as part of HPCToolkit.

Before you push your changes

  1. If you are fixing a bug, please report it first. If you are adding a feature, please write a request first. In both cases search our issue tracker for any other bugs/features related to your change. These issues help continuity if a bug reappears later or a feature needs redesigned, as well as for milestone/epic planning.

  2. git rebase your commits onto the latest tip of develop (e.g. git pull -r origin develop). We will not accept MRs that contain merge commits.

  3. Double-check that the author name and email on your commits is valid and matches your email on GitLab. This helps ensure your commits are properly attributed to you and to your GitLab account.

    [!important] If your commits have the wrong author, set git config user.name 'Thomas Jefferson' and git config user.email 'thomas.jefferson@president.gov', then replace the authorship on your commits with git commit --amend --reset-author.
    For many commits, try:

    git rebase -x 'git commit --amend --reset-author --no-edit' develop

Submitting your first merge request (MR)

  1. (If you haven't already,) create a fork of the repository. This provides a place to store and share your changes.

  2. For new features, update the User's Manual (doc/src/users/) to include your new features. This is what makes your changes usable by others.

    [!note] The meson compile docs target builds just the documentation. meson compile docs-serve starts a local HTTP server to view this rendered documentation.

  3. git push your changes to your new fork. Name your Git branch something related to the goal of your changes.

  4. Create an MR for your changes. Feel free to mark it as a Draft: if you are still finalizing the details.

    [!note] Include references to any related issues in your MR description, with phrases such as Fixes #123, Resolves #456 or Implements #789. This automatically closes the issues when the MR gets merged and helps others find your changes.

  5. Check and fix any errors seen in the CI for your MR.

  6. Wait patiently for a response and/or review. Be amenable to any requested changes.

Tips and tricks for a successful MR

  1. Follow best practices for the programming language. While we don't have a rigid coding style, consider reading and following the C++ Core Guidelines and the LLVM Coding Standards.

  2. Fix any compiler warnings you see. Compiler warnings are errors (or unexpected behaviors) waiting to happen, cleaning them up improves your code for the better.

  3. Run our linters/formatters locally before pushing your changes. CI will run the following linters/formatters and will fail before your code even has a chance to run if they fail:

    1. pre-commit hooks via pre-commit run -a, and
    2. clang-format via ninja clang-format.

  4. When possible, add a test that your changes are working as intended. Even simple "doesn't crash" tests find plenty of bugs.

  5. Run the tests (meson test) at least once before submitting. The CI runs all the tests and will fail if any of them fail unexpectedly (or pass unexpectedly).

  6. Before you submit, consider squashing your changes into a small set of Git commits with clear commit messages. This makes tools like git blame and git bisect more effective, and overall makes the history easier to search later.

    [!tip] You can squash your changes locally using either of the following git commands:

    Squashing commits with git reset

    To squash the last 5 commits together:

    $ git reset --soft HEAD~5
$ git commit -s

    To squash all changes made in the current branch compared to the base develop:

    $ git reset --soft $(git merge-base HEAD develop)
$ git commit -s
    Squashing commits with git rebase

    During an interactive rebase (git rebase -i), a commit can be squashed into the last pick'd commit using the fixup or squash commands. Since squashing commits is so common, Git can mark commits to be squashed away ahead of time. For example, suppose you made a few commits:

    $ git commit -s -m 'Implement the fuzzball API'
$ git commit -s -m 'Document available vacuums'

    Now you notice an bug in the implementation. You can fix it and mark the commit to be squashed into the implementation commit with:

    $ git commit -s --fixup HEAD~1
$ git log --oneline
....... fixup! Implement the fuzzball API
....... Document available vacuums
....... Implement the fuzzball API

    You can even add more commits afterwards and push the branch:

    $ git commit -s -m 'Continuously report dust status'
$ git push   # This will automatically mark an existing MR as draft due to the fixup! commit

    And then finally squash them down during your next rebase:

    $ git rebase -i --autosquash develop
$ git log --oneline
....... Continuously report dust status
....... Update documentation
....... Implement the fuzzball API

    These commands rewrite history, so after the history has been rewritten you will need to force the push:

    $ git push --force-with-lease