kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/web/site/contributing.md (about)

     1  ---
     2  layout: page
     3  title: Contributing
     4  permalink: /contributing/
     5  ---
     6  
     7  * toc
     8  {:toc}
     9  
    10  ## Getting started with the Kythe codebase
    11  
    12  [Instructions to build Kythe from source]({{site.baseuri}}/getting-started)
    13  
    14  ## Code review
    15  
    16  All changes to Kythe must go through code review before being submitted, and
    17  each individual or corporate contributor must sign an appropriate [Contributor
    18  License Agreement](https://cla.developers.google.com/about).  Once your CLA is
    19  submitted (or if you already submitted one for another Google project), make a
    20  commit adding yourself to the
    21  [AUTHORS]({{site.data.development.source_browser}}/AUTHORS) and
    22  [CONTRIBUTORS]({{site.data.development.source_browser}}/CONTRIBUTORS)
    23  files. This commit can be part of your first Pull Request.
    24  
    25  The Kythe team has chosen to use GitHub [Pull Requests](https://guides.github.com/activities/forking/)
    26  for code review.
    27  
    28  ## Linting and Testing
    29  
    30  Run `./tools/git/setup_hooks.sh` to initialize the standard Git hooks used by
    31  the Kythe developers.  This ensures that each commit passes all unit/lint tests
    32  and that commit descriptions follow the [Conventional
    33  Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) specification
    34  *before* a requesting code review.  If necessary, use `git commit --no-verify`
    35  to bypass these checks.  In addition to the tools necessary to build Kythe, the
    36  following are necessary to run the installed hooks:
    37  
    38  - pre-commit
    39  - buildifier
    40  - clang-format (>= 11)
    41  - gofmt
    42  - golint
    43  - google-java-format
    44  - jq
    45  - shellcheck
    46  
    47  Each Pull Request will also require a gambit of tests run Google Cloud Build.
    48  All non-maintainers will require a Kythe team member to add a `/gcbrun` comment
    49  in each Pull Request to verify the PR should be checked by presubmits.
    50  
    51  ### Style formatting
    52  
    53  Kythe C++ code follows the Google style guide. You can run `clang-format` to do
    54  this automatically:
    55  
    56  {% highlight bash %}
    57  clang-format -i --style=file <filename>
    58  {% endhighlight %}
    59  
    60  If you forgot to do this for a commit, you can amend it easily:
    61  
    62  {% highlight bash %}
    63  clang-format -i --style=file $(git show --pretty="" --name-only <SHA1>)
    64  git commit --amend
    65  {% endhighlight %}
    66  
    67  Likewise, all Java code should be formatted by the latest version of
    68  `google-java-format` and Go code should pass through `gofmt`.
    69  
    70  ## Contribution Ideas
    71  
    72  Along with working off of our [tasks
    73  list]({{site.data.development.issue_tracker}}) (and, in particular, the
    74  [Wishlist]({{site.data.development.github}}/labels/wishlist)),
    75  there are many ways to contribute to Kythe.
    76  
    77  ### New Extractors and Indexers
    78  
    79  Kythe is built on the idea of having a common set of tools across programming
    80  languages so Kythe is always happy to
    81  [add another language to its family]({{site.baseurl}}/docs/kythe-compatible-compilers.html).
    82  
    83  ### Build System Integration
    84  
    85  In order to use Kythe's compilation extractors, they must be given precise
    86  information about how a compilation is processed.  Currently, Kythe has
    87  [built-in support]({{site.data.development.source_browser}}/kythe/extractors/bazel/extract.sh)
    88  for Bazel and rudimentary support for
    89  [CMake]({{site.data.development.source_browser}}/kythe/extractors/cmake/).
    90  Contributing support for more build systems like [Gradle](https://gradle.org)
    91  will greatly help the ease of use for Kythe and increase the breadth of what it
    92  can index.
    93  
    94  ### User Interfaces
    95  
    96  Kythe emits a lot of data and there are *many* ways to interpret/display it all.
    97  Ideas for visualizers include an interactive graph, a documentation browser and a source file hierarchical overview.