github.com/NVIDIA/aistore@v1.3.23-0.20240517131212-7df6609be51d/CONTRIBUTING.md (about)

     1  # Contributing to AIStore
     2  
     3  The AIStore project repository follows an open source model where anyone is allowed and encouraged to contribute. However, contributing to AIStore has a few guidelines that must be followed.
     4  
     5  
     6  ## Contribution Workflow
     7  
     8  The AIStore project repository maintains a contribution structure in which everyone *proposes* changes to the codebase via *pull requests*. To contribute to AIStore:
     9  
    10  1. [Fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork),
    11  2. [Create branch for issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue),
    12  3. [Test changes](#testing-changes),
    13  4. [Format changes](#formatting-changes),
    14  5. [Commit changes (w/ sign-off)](#signing-off-commits),
    15  6. [Squash commits](#squashing-changes),
    16  5. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
    17  
    18  
    19  #### Formatting Changes
    20  
    21  AIStore maintains a few formatting rules to ensure a consistent coding style. These rules are checked and enforced by `black`, `pylint`, `gofmt`, etc.  Before committing any changes, make sure to check (or fix) all changes against the formatting rules as follows:
    22  
    23  ```console
    24  $ cd aistore
    25  
    26  # Run linter on entire codebase
    27  $ make lint
    28  
    29  # Check code formatting
    30  $ make fmt-check
    31  
    32  # Fix code formatting
    33  $ make fmt-fix
    34  
    35  # Check for any misspelled words
    36  $ make spell-check
    37  ```
    38  
    39  > For more information, run `make help`.
    40  
    41  
    42  #### Testing Changes
    43  
    44  Before committing any changes, run the following tests to verify any added changes to the codebase:
    45  
    46  ```console
    47  $ cd aistore
    48  
    49  # Run short tests
    50  $ BUCKET=tmp make test-short
    51  
    52  # Run all tests
    53  $ BUCKET=<existing-cloud-bucket> make test-long
    54  ```
    55  
    56  To run Python-related tests:
    57  
    58  ```console
    59  $ cd aistore/python
    60  
    61  # Run all Python tests
    62  $ make python_tests
    63  
    64  # Run Python sdk tests
    65  $ make python_sdk_tests
    66  
    67  # Run Python ETL tests
    68  $ make python_etl_tests
    69  
    70  # Run Python botocore monkey patch tests
    71  $ make python_botocore_tests
    72  ```
    73  
    74  
    75  #### Signing-Off Commits
    76  
    77  All contributors must *sign-off* on each commit. This certifies that each contribution is that contributor's original work per the following *Developer Certificate of Origin*[^developer-certificate-of-origin].
    78  
    79  [^developer-certificate-of-origin]: **Developer Certificate of Origin**
    80      ```
    81      Developer Certificate of Origin
    82      Version 1.1
    83  
    84      Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
    85      1 Letterman Drive
    86      Suite D4700
    87      San Francisco, CA, 94129
    88  
    89      Everyone is permitted to copy and distribute verbatim copies of this
    90      license document, but changing it is not allowed.
    91  
    92  
    93      Developer's Certificate of Origin 1.1
    94  
    95      By making a contribution to this project, I certify that:
    96  
    97      (a) The contribution was created in whole or in part by me and I
    98          have the right to submit it under the open source license
    99          indicated in the file; or
   100  
   101      (b) The contribution is based upon previous work that, to the best
   102          of my knowledge, is covered under an appropriate open source
   103          license and I have the right under that license to submit that
   104          work with modifications, whether created in whole or in part
   105          by me, under the same open source license (unless I am
   106          permitted to submit under a different license), as indicated
   107          in the file; or
   108  
   109      (c) The contribution was provided directly to me by some other
   110          person who certified (a), (b) or (c) and I have not modified
   111          it.
   112  
   113      (d) I understand and agree that this project and the contribution
   114          are public and that a record of the contribution (including all
   115          personal information I submit with it, including my sign-off) is
   116          maintained indefinitely and may be redistributed consistent with
   117          this project or the open source license(s) involved.
   118      ```
   119  
   120  Commits can be signed off by using the `git` command's `--signoff` (or `-s`) option:
   121  
   122  ```bash
   123  $ git commit -s -m "Add new feature"
   124  ```
   125  
   126  This will append the following type of footer to the commit message:
   127  
   128  ```
   129  Signed-off-by: Your Name <your@email.com>
   130  ```
   131  
   132  > **Note**: Commits that are not signed-off cannot be accepted or merged.
   133  
   134  
   135  #### Squashing Commits
   136  
   137  If a pull request contains more than one commit, [squash](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) all commits into one. 
   138  
   139  The basic squashing workflow is as follows:
   140  
   141  ```console
   142  git checkout <your-pr-branch>
   143  git rebase -i HEAD~<# of commits to squash>
   144  ```
   145  
   146  
   147  ## Raise an Issue 
   148  
   149  If a bug requires more attention, raise an issue [here](https://github.com/NVIDIA/aistore/issues). We will try to respond to the issue as soon as possible.
   150  
   151  Please give the issue an appropriate title and include detailed information on the issue at hand.
   152  
   153  ---