Skip to content

Latest commit

 

History

History
78 lines (43 loc) · 3.69 KB

CONTRIBUTING.md

File metadata and controls

78 lines (43 loc) · 3.69 KB
Raw

Welcome! Thank you for contributing to Apache Pekko!

We follow the standard GitHub fork & pull approach to pull requests. Just fork the official repo, develop in a branch, and submit a PR!

You're always welcome to submit your PR straight away and start the discussion (without reading the rest of this wonderful doc, or the README.md). The goal of these notes is to make your experience contributing to Apache Pekko as smooth and pleasant as possible. We're happy to guide you through the process once you've submitted your PR.

The Pekko Community

In case of questions about the contribution process or for discussion of specific issues please use the GitHub Discussions for this project.

You may also check out the Pekko dev mailing list.

Antora-based Pekko Documentation

This folder contains the sources for parts of future Pekko Platform Guide web site. The equivalent Akka Platform Guide web site should be a useful guide until we are complete.

This folder is structured as follows:

  • The root directory contains the Makefile for the documentation generation process.
  • The structured documentation is located under docs-source/.

Contributions to the documentation are welcome and encouraged. If you are unfamiliar with the project or with asciidoc, please read the contribution guidelines below.

Antora extension

Find some hints about the Lightbend Antora theme at https://lightbend.github.io/antora-supplemental-ui-lightbend-theme/build/site/index.html

The theme sources are in a Lightbend-private project at https://github.com/lightbend/antora-supplemental-ui-lightbend-theme

Contributing to the Pekko Documentation

Detailed information about working with the documentation is provided in the docs-source folder.

Building the Documentation

This part of the Pekko documentation is built using Antora, from asciidoc sources. The building process is managed by make using the makefile script.

To build the documentation, use make with the following commands:

  • make local-preview Generates the documentation and serves it at localhost:8000.

  • make html-author-mode

    Generates the documentation, in 'author' mode, to display review comments and TODOs. The result is available at target/staging/index.html.

  • make all (default)

    Generates the complete documentation bundle.

  • make html

    Generates the html documentation and homepage.

  • make check-links

    Checks that the external links point to a reachable URL.

  • make list-todos

    List all the TODOs, review comments, unresolve references, etc. from the documentation.

Synchronize code for different parts of the tutorial

Each part of the tutorial has full source code in directories in docs-source/docs/modules/microservices-tutorial/examples/.

Many files are identical and maintained with scripts/copy-identical-files.sh, which copies the files.

The 00 directory is the "empty" project corresponds to the generated code from a future seed template.

It's often easiest to make changes to the example in the full example (last part of the tutorial) and then propagate those changes backwards with scripts/copy-identical-files.sh and manual edits of non-identical files. IntelliJ has a good diff tool for propagating changes between files and folders.

PR validation in GitHub Actions CI will run the scripts/copy-identical-files.sh and fail the build if expected identical files are different.