Skip to content

Latest commit

 

History

History
206 lines (136 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

206 lines (136 loc) · 4.64 KB

Contributing

Pull Requests

Creating a Pull Request

This book has been designed so that people can easily expand it. To request us to review changes that you create, you will need to create a pull request. Creating a pull request is described in this tutorial.

File Location/Types

ebook

This directory holds all of the translations of the eBook.

ebook/{LANG}

In the ebook directory we have the translations of the eBook in different languages.

If you are adding a new translation, make sure to make a copy of the ./ebook/en directory and use the language code as the new directory name.

ebook/{LANG}/content

All the Markdown files for the '101 Linux commands' eBook are located within the content directory for the specific language.

For example if you are adding a Bulgarian translation copy the ./ebook/en folder to ./ebook/bg, translate the .md files in the content directory and submit a PR.

eBook Generation

The project uses Ibis Next developed by Roberto Butti, forked from the original Ibis by Mohamed Said.

Ibis Next supports generating PDF, EPUB, and HTML formats from Markdown content.

Setup and Usage

  1. Install dependencies:
composer install
  1. Generate PDF (light theme):
composer run pdf
  1. Generate PDF (dark theme):
composer run pdf-dark
  1. Generate EPUB:
composer run epub
  1. Generate HTML:
composer run html

For more information about Ibis Next, visit: Getting started with Ibis Next

Contribution Examples

Typical Git workflow

  1. Fork the repository on GitHub and clone your fork locally.
git clone https://github.com/<your-user>/101-linux-commands.git
cd 101-linux-commands
  1. Create a dedicated branch for your changes.
git checkout -b feature/add-cli-example
  1. While you work, check your status and stage files deliberately.
git status
git add CONTRIBUTING.md
  1. Commit with a descriptive message and push your branch.
git commit -m "docs: add CLI contribution examples"
git push origin feature/add-cli-example

Running the CLI locally

  1. Move into the CLI workspace.
cd cli
  1. (Recommended) Create and activate a virtual environment. Use the command that matches your shell:
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# macOS/Linux
source .venv/bin/activate
  1. Install the dependencies and the CLI in editable mode.
pip install -r requirements.txt
pip install -e .
  1. Confirm the CLI works.
linux-cli --help
# or run directly without installation
python -m cli.cli hello greet --name "Linux Contributor"
# greet someone specific using the installed entry point
linux-cli hello greet --name "Linux Contributor"

Adding a new command

  1. Create a new command module inside cli/commands/. Example (cli/commands/ping.py):
import typer

app = typer.Typer(help="Ping command group")


@app.command()
def once():
    """Print a ping message."""
    typer.echo("pong")
  1. Register the command with the main Typer app in cli/cli.py:
from commands import hello, ping

app = typer.Typer(help="101 Linux Commands CLI 🚀")
app.add_typer(hello.app, name="hello")
app.add_typer(ping.app, name="ping")

  1. Add or update tests in cli/test_cli.py to cover your new command. Mirror the existing hello command tests and update expectations.

  2. Run the CLI manually to verify your command behaves as expected.

python -m cli.cli ping once

Running tests

  1. Ensure you're in the cli directory with your virtual environment activated.

  2. Install the testing dependency if you haven't already.

pip install pytest
  1. Execute the test suite:
pytest
  1. (Optional but encouraged) Run the additional quality checks that the workflow executes:
black cli/
isort cli/
flake8 cli/
mypy cli/

Issue Creation

In the event that you have an issue using the guide or have a suggestion for a change but don't want to contribute changes, we are more than happy to help. Make sure that when you create your issue, it follows the format for the type of issue you select (it has individual templates for each issue type).

Issue template types include the following:

  • Bug Reporting
  • Feature Requests
  • Help Requests