Skip to content

Latest commit

 

History

History
58 lines (42 loc) · 4.47 KB

CONTRIBUTING.adoc

File metadata and controls

58 lines (42 loc) · 4.47 KB
Raw

Contributors Guide (or, do not be afraid to break things)

The Starknet Book is an open-source Cairo/Starknet teaching curriculum written by starknet-edu and the Starknet community. We welcome all contributions to this repository to help enrich the Starknet community.

Note

Please review this section, however, please reach out to the maintainers if you have any questions, concerns or want to add a new chapter/subchapter (default to @espejelomar on Twitter or Telegram). We are here to help you contribute to the Starknet Book and make it a valuable resource for the Starknet community.

How to Contribute

Follow these steps to contribute to the Starknet Book:

  1. Run the book locally (see "Running the Book Locally" section below).

  2. Familiarize yourself with the book structure (see "The Book Structure in Antora" section below).

  3. Find or propose an issue to work on (if it is a small change, create a PR directly). Comment on the issue to ask if it’s available or create a new issue and tag a maintainer (by default, tag l-henri or @omarespejel).

  4. Work on the issue in a branch of your personal fork of the main repository (refer to this guide for help).

  5. Create a pull request (PR) to merge your changes into the main repository. Tag a maintainer in the PR for review (by default, tag l-henri or @omarespejel). Allow maintainers to make commits to your branch if needed.

  6. Wait for the repository maintainers to review your changes.

  7. If the issue is addressed, the repository maintainers will merge your PR.

Now, let’s dive into the details.

Running the Book Locally

Before submitting a PR, make sure you can run the book locally by following these steps:

  1. Clone the repository locally: git clone https://github.com/starknet-edu/starknetbook.git.

  2. Change directory to the repository: cd starknetbook.

  3. Install the lunr extension: npm i @antora/lunr-extension.

  4. Run the book locally: npx antora --fetch antora-playbook.yml. If a missing extension error appears, install the extension as shown in step 3.

The Book Structure in Antora

The Starknet Book is structured to be compatible with Antora, a static site generator. Key components include:

  • antora-playbook.yml: Configuration for the Antora site generator (contributors don’t need to edit this).

  • chapters/antora.yml: Main outline of the book where new chapters are added (e.g., add modules/chapter_35/nav.adoc for Chapter 35).

  • chapters/modules/: Contains the content of the book, with each chapter in a separate folder (e.g., chapters/modules/chapter_35/). Chapter folders include:

    • pages/: Contains asciidoc files with the chapter content.

    • nav.adoc: Contains the chapter outline and references to section files in pages/.

    • images/: Contains images for the chapter.

    • Other directories (e.g., contracts/): Contain code or other resources for the chapter.

Content Guidelines

To ensure the Starknet Book is comprehensive, consistent, and easy to understand, please adhere to the following content guidelines when contributing:

  • Write in a clear and concise manner. Avoid jargon and overly technical language whenever possible. The primary goal is to make the content accessible to as many readers as possible.

  • Use proper grammar, punctuation, and spelling. This ensures a professional appearance and makes the content easier to understand.

  • Break down complex topics into smaller sections or subsections. This makes the content more digestible and helps readers grasp the concepts more easily.

  • Include relevant code examples and illustrations to clarify concepts. Make sure to test your code examples for accuracy and functionality.

  • Whenever possible, use practical examples that readers can apply in real-world situations.

  • Maintain a consistent tone and style throughout the content. The Starknet Book should have a unified voice that makes it feel like a cohesive work.

  • Keep the content up-to-date. If you come across outdated information, update it or notify the maintainers about the issue.

  • Be respectful and considerate in your interactions with other contributors. Collaboration is key to creating and maintaining a high-quality resource.

By following these guidelines, you can help create a valuable learning resource for the Starknet community. Remember, every contribution, no matter how small, makes a difference. Thank you for your efforts in helping to grow and strengthen the Starknet ecosystem.