github.com/lineaje-labs/syft@v0.98.1-0.20231227153149-9e393f60ff1b/CONTRIBUTING.md (about)

     1  [#](#) Contributing to Syft
     2  
     3  If you are looking to contribute to this project and want to open a GitHub pull request ("PR"), there are a few guidelines of what we are looking for in patches. Make sure you go through this document and ensure that your code proposal is aligned.
     4  
     5  ## Setting up your environment
     6  
     7  Before you can contribute to Syft, you need to configure your development environment.
     8  
     9  ### Debian setup
    10  
    11  You will need to install Go. The version on https://go.dev works best, using the system golang doesn't always work the way you might expect.
    12  
    13  Refer to the go.mod file in the root of this repo for the recommended version of Go to install.
    14  
    15  You will also need Docker. There's no reason the system packages shouldn't work, but we used the official Docker package. You can find instructions for installing Docker in Debian [here](https://docs.docker.com/engine/install/debian/).
    16  
    17  You also need to install some Debian packages
    18  
    19  ```sh
    20  sudo apt-get install build-essential zip bc libxml2-utils git
    21  ```
    22  
    23  ## Configuring Git
    24  
    25  You will need to configure your git client with your name and email address. This is easily done from the command line.
    26  
    27  ```text
    28  $ git config --global user.name "John Doe"
    29  $ git config --global user.email "john.doe@example.com"
    30  ```
    31  
    32  This username and email address will matter later in this guide.
    33  
    34  ## Fork the repo
    35  
    36  You should fork the Syft repo using the "Fork" button at the top right of the Syft GitHub [site](https://github.com/anchore/syft/). You will be doing your development in your fork, then submit a pull request to Syft. There are many resources how to use GitHub effectively, we will not cover those here.
    37  
    38  ## Adding a feature or fix
    39  
    40  If you look at the Syft [Issue](https://github.com/anchore/syft/issues) there are plenty of bugs and feature requests. Maybe look at the [good first issue](https://github.com/anchore/syft/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) list if you're not sure where to start.
    41  
    42  ## Commit guidelines
    43  
    44  In the Syft project we like commits and pull requests (PR) to be easy to understand and review. Open source thrives best when everything happening is over documented and small enough to be understood.
    45  
    46  ### Granular commits
    47  
    48  Please try to make every commit as simple as possible, but no simpler. The idea is that each commit should be a logical unit of code. Try not to commit too many tiny changes, for example every line changed in a file as a separate commit. And also try not to make a commit enormous, for example committing all your work at the end of the day.
    49  
    50  Rather than try to follow a strict guide on what is or is not best, we try to be flexible and simple in this space. Do what makes the most sense for the changes you are trying to include.
    51  
    52  ### Commit title and description
    53  
    54  Remember that the message you leave for a commit is for the reviewer in the present, and for someone (maybe you) changing something in the future. Please make sure the title and description used is easy to understand and explains what was done. Jokes and clever comments generally don't age well in commit messages. Just the facts please.
    55  
    56  ## Sign off your work
    57  
    58  The `sign-off` is an added line at the end of the explanation for the commit, certifying that you wrote it or otherwise have the right to submit it as an open-source patch. By submitting a contribution, you agree to be bound by the terms of the DCO Version 1.1 and Apache License Version 2.0.
    59  
    60  Signing off a commit certifies the below Developer's Certificate of Origin (DCO):
    61  
    62  ```text
    63  Developer's Certificate of Origin 1.1
    64  
    65  By making a contribution to this project, I certify that:
    66  
    67     (a) The contribution was created in whole or in part by me and I
    68         have the right to submit it under the open source license
    69         indicated in the file; or
    70  
    71     (b) The contribution is based upon previous work that, to the best
    72         of my knowledge, is covered under an appropriate open source
    73         license and I have the right under that license to submit that
    74         work with modifications, whether created in whole or in part
    75         by me, under the same open source license (unless I am
    76         permitted to submit under a different license), as indicated
    77         in the file; or
    78  
    79     (c) The contribution was provided directly to me by some other
    80         person who certified (a), (b) or (c) and I have not modified
    81         it.
    82  
    83     (d) I understand and agree that this project and the contribution
    84         are public and that a record of the contribution (including all
    85         personal information I submit with it, including my sign-off) is
    86         maintained indefinitely and may be redistributed consistent with
    87         this project or the open source license(s) involved.
    88  ```
    89  
    90  All contributions to this project are licensed under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/).
    91  
    92  When committing your change, you can add the required line manually so that it looks like this:
    93  
    94  ```text
    95  Signed-off-by: John Doe <john.doe@example.com>
    96  ```
    97  
    98  Creating a signed-off commit is then possible with `-s` or `--signoff`:
    99  
   100  ```text
   101  $ git commit -s -m "this is a commit message"
   102  ```
   103  
   104  To double-check that the commit was signed-off, look at the log output:
   105  
   106  ```text
   107  $ git log -1
   108  commit 37ceh170e4hb283bb73d958f2036ee5k07e7fde7 (HEAD -> issue-35, origin/main, main)
   109  Author: John Doe <john.doe@example.com>
   110  Date:   Mon Aug 1 11:27:13 2020 -0400
   111  
   112      this is a commit message
   113  
   114      Signed-off-by: John Doe <john.doe@example.com>
   115  ```
   116  
   117  ## Test your changes
   118  
   119  This project has a `Makefile` which includes many helpers running both unit and integration tests. You can run `make help` to see all the options. Although PRs will have automatic checks for these, it is useful to run them locally, ensuring they pass before submitting changes. Ensure you've bootstrapped once before running tests:
   120  
   121  ```text
   122  $ make bootstrap
   123  ```
   124  
   125  You only need to bootstrap once. After the bootstrap process, you can run the tests as many times as needed:
   126  
   127  ```text
   128  $ make unit
   129  $ make integration
   130  ```
   131  
   132  You can also run `make all` to run a more extensive test suite, but there is additional configuration that will be needed for those tests to run correctly. We will not cover the extra steps here.
   133  
   134  ## Pull Request
   135  
   136  If you made it this far and all the tests are passing, it's time to submit a Pull Request (PR) for Syft. Submitting a PR is always a scary moment as what happens next can be an unknown. The Syft project strives to be easy to work with, we appreciate all contributions. Nobody is going to yell at you or try to make you feel bad. We love contributions and know how scary that first PR can be.
   137  
   138  ### PR Title and Description
   139  
   140  Just like the commit title and description mentioned above, the PR title and description is very important for letting others know what's happening. Please include any details you think a reviewer will need to more properly review your PR.
   141  
   142  A PR that is very large or poorly described has a higher likelihood of being pushed to the end of the list. Reviewers like PRs they can understand and quickly review.
   143  
   144  ### What to expect next
   145  
   146  Please be patient with the project. We try to review PRs in a timely manner, but this is highly dependent on all the other tasks we have going on. It's OK to ask for a status update every week or two, it's not OK to ask for a status update every day.
   147  
   148  It's very likely the reviewer will have questions and suggestions for changes to your PR. If your changes don't match the current style and flow of the other code, expect a request to change what you've done.
   149  
   150  ## Document your changes
   151  
   152  And lastly, when proposed changes are modifying user-facing functionality or output, it is expected the PR will include updates to the documentation as well. Syft is not a project that is heavy on documentation. This will mostly be updating the README and help for the tool.
   153  
   154  If nobody knows new features exist, they can't use them!