github.com/treeverse/lakefs@v1.24.1-0.20240520134607-95648127bfb0/docs/project/contributing.md (about)

     1  ---
     2  title: Contributing to lakeFS
     3  description: lakeFS community welcomes your contribution. To make the process as seamless as possible, we recommend reading this contribution guide first.
     4  parent: The lakeFS Project
     5  redirect_from:
     6     - /contributing.html
     7  ---
     8  
     9  # Contributing to lakeFS
    10  
    11  Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
    12  
    13  Please read through this document before submitting any issues or pull requests to ensure that we have all the necessary information to effectively respond to your bug report or contribution.
    14  
    15  *Don't know where to start?* Reach out on the #dev channel on [our Slack](https://lakefs.io/slack) and we will help you get started. We also recommend this [free series](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github){:target="_blank"} about contributing to OSS projects.
    16  {: .note }
    17  
    18  ## Getting Started
    19  
    20  Before you get started, we kindly ask that you:
    21  
    22  * Check out the [code of conduct](https://github.com/treeverse/lakeFS/blob/master/CODE_OF_CONDUCT.md).
    23  * Sign the [lakeFS CLA](https://cla-assistant.io/treeverse/lakeFS) when making your first pull request (individual / corporate)
    24  * Submit any security issues directly to [security@treeverse.io](mailto:security@treeverse.io).
    25  * Contributions should have an associated [GitHub issue](https://github.com/treeverse/lakeFS/issues/). 
    26  * Before making major contributions, please reach out to us on the #dev channel on [Slack](https://lakefs.io/slack).
    27    We will make sure no one else is working on the same feature. 
    28  
    29  ## Setting up an Environment
    30  
    31  *This section was tested on macOS and Linux (Fedora 32, Ubuntu 20.04) - Your mileage may vary*
    32  
    33  
    34  Our [Go release workflow](https://github.com/treeverse/lakeFS/blob/master/.github/workflows/goreleaser.yaml) holds the Go and Node.js versions we currently use under _go-version_ and _node-version_ compatibly. The Java workflows use [Maven 3.8.x](https://github.com/actions/runner-images/blob/bc22983319daa620b2ad01a74b68f6f462d86241/images/linux/Ubuntu2004-Readme.md) (but any recent version of Maven should work).
    35  
    36  1. Install the required dependencies for your OS:
    37     1. [Git](https://git-scm.com/downloads)
    38     1. [GNU make](https://www.gnu.org/software/make) (probably best to install from your OS package manager such as [apt](https://en.wikipedia.org/wiki/APT_(software)) or [brew](https://brew.sh/))
    39     1. [Docker](https://docs.docker.com/get-docker/)
    40     1. [Go](https://golang.org/doc/install)
    41     1. [Node.js & npm](https://www.npmjs.com/get-npm)
    42     1. [Maven](https://maven.apache.org/) to build and test Spark client codes.
    43     1. Java 8
    44        * Apple M1 users can install this from [Azul Zulu Builds for Java JDK](https://www.azul.com/downloads/?package=jdk). Builds for Intel-based Macs are available from [java.com](https://www.java.com/en/download/help/mac_install.html).
    45     1. *Optional* - [PostgreSQL 11](https://www.postgresql.org/docs/11/tutorial-install.html) (useful for running and debugging locally)
    46     1. *Optional* - [Rust & Cargo](https://www.rust-lang.org/tools/install) (only needed if you want to build the Delta Lake diff plugin)
    47     1. *Optional* - [Buf CLI](https://buf.build/docs/installation) (only needed if you like to update Protocol Buffer files)
    48  
    49  1. [Clone](https://github.com/git-guides/git-clone) the [repository from GitHub](https://github.com/treeverse/lakeFS). 
    50  
    51      _This gives you read-only access to the repository. To contribute, see the next section._
    52  
    53  1. Build the project:
    54  
    55     ```shell
    56     make build
    57     ```
    58  
    59     _Note: `make build` won't work for Windows users._
    60  
    61  1. Make sure tests are passing. The following should not return any errors: 
    62  
    63     ```shell
    64     make test
    65     ```
    66  
    67  ## Before creating a pull request
    68  
    69  1. Review this document in full.
    70  1. Make sure there's an open [issue on GitHub](https://github.com/treeverse/lakeFS/issues) that this pull request addresses, and that it isn't labeled `x/wontfix`.
    71  1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [lakeFS repository](https://github.com/treeverse/lakeFS).
    72  1. If you're adding new functionality, create a new branch named `feature/<DESCRIPTIVE NAME>`.
    73  1. If you're fixing a bug, create a new branch named `fix/<DESCRIPTIVE NAME>-<ISSUE NUMBER>`.
    74  
    75  ## Testing your change
    76  
    77  Once you've made the necessary changes to the code, make sure the tests pass:
    78  
    79  Run unit tests:
    80  
    81  ```shell
    82  make test
    83  ```
    84  
    85  Check that linting rules are passing. 
    86  
    87  ```shell
    88  make checks-validator
    89  ```
    90  
    91  You will need GNU diff to run this. On the macOS it can be installed with `brew install diffutils`
    92  {: .note }
    93  
    94  lakeFS uses [go fmt](https://golang.org/cmd/gofmt/) as a style guide for Go code.
    95  
    96  Run system-tests:
    97  
    98  ```shell
    99  make system-tests
   100  ```
   101  
   102  Want to dive deeper into our system tests infrastructure? Need to debug the tests? Follow [this documentation](https://github.com/treeverse/lakeFS/blob/master/esti/docs/README.md).
   103  {: .note }
   104  
   105  ## Submitting a pull request
   106  
   107  Open a GitHub pull request with your change. The PR description should include a brief explanation of your change.
   108  You should also mention the related GitHub issue. If the issue should be automatically closed after the merge, please [link it to the PR](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).
   109  
   110  After submitting your pull request, [GitHub Actions](https://github.com/treeverse/lakeFS/actions) will automatically run tests on your changes and make sure that your updated code builds and runs on Go 1.19.x.
   111  
   112  Check back shortly after submitting your pull request to make sure that your code passes these checks. If any of the checks come back with a red X, then do your best to address the errors.
   113  
   114  A developer from our team will review your pull request, and may request some changes to it. After the request is approved, it will be merged to our main branch.
   115  
   116  
   117  
   118  ## Documentation
   119  
   120  Any contribution to the docs, whether it is in conjunction with a code contribution or as a standalone, is appreciated.
   121  
   122  Documentation of features and changes in behaviour should be included in the pull request.
   123  You can create separate pull requests for documentation changes only.
   124  
   125  To learn how to contribute to the lakeFS documentation see [this page](./docs/index.html), which also includes details on how to build the documentation locally. 
   126  
   127  ## CHANGELOG.md
   128  
   129  Any user-facing change should be labeled with `include-changelog`.
   130  The PR title should contain a concise summary of the feature or fix and the description should have the GitHub issue number.
   131  When we publish a new version of lakeFS, we will add this to the relevant version section of the changelog.
   132  If the change should not be included in the changelog, label it with `exclude-changelog`.