docs/contributing.rst

:author: rules_proto_grpc
:description: Changelog for the rules_proto_grpc Bazel rules
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Developers, Contributing


Contributing
============

Contributions are very welcome on this project. Issues should be raised for bugs and feature
requests. Pull requests should be targeted at the master branch and will run against CI.

.. note:: The rules in the repo are generated by the code in tools/rulegen and the output rules
  should therefore not be edited directly. However, if you are not comfortable editing this code,
  please submit a PR with just the output files edited and we'll help update the generator to get
  the desired result.


Code Layout
-----------

Each language ``{lang}`` has files in a number of locations:

1. ``docs/{lang}.rst``: Generated documentation for the language rules

2. ``modules/{lang}/MODULE.bazel``: Rule dependencies for the language

3. ``modules/{lang}/{rule}.bzl``: Rule implementations of the form ``{lang}_{kind}_{type}``, where ``kind``
   is one of ``proto|grpc`` and ``type`` is one of ``compile|library``

4. ``modules/{lang}/BUILD.bazel``: ``proto_plugin()`` declarations for the available plugins for the
   language

5. ``examples/{lang}/{rule}/``: Generated workspace demonstrating standalone usage of the rule

6. ``examples/{lang}/routeguide/``: Example routeguide example implementation, if available


Rule Generation
---------------

To help maintain consistency of the rule implementations and documentation, all of the rule
implementations are generated by the tool ``//tools/rulegen``. Changes in the main ``README.rst``
should be placed in ``tools/rulegen/README.header.rst`` or ``tools/rulegen/README.footer.rst```.
Changes to generated rules should be put in the source files (example: ``tools/rulegen/java.go``).