Contributing to the Beer Project¶

Thank you for your interest in contributing to the Beer project! We welcome contributions from everyone. This document will guide you through the process of setting up your development environment and submitting your contributions.

Getting Started¶

Fork, Clone, and Branch¶

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/your-username/beer.git
cd beer

Create a new branch for your contribution:
```
git checkout -b your-feature-branch
```

Setting up the Development Environment¶

We use pyproject.toml to manage project dependencies. Here's how to set up your development environment:

Ensure you have Python 3.12 installed on your system.

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create a new virtual environment and install dependencies:

uv venv -p 3.12
source .venv/bin/activate  # On Unix or MacOS
.venv\Scripts\activate  # On Windows
uv pip install -e ".[dev,lint]"

This will install the project along with its dependencies, including development and linting tools.

Adding Content¶

Adding a New Problem¶

Create a new Markdown file in the appropriate directory (e.g., docs/fifty/ for the Fifty Challenging Problems).
Use the similar [template]https://datahonor.com/beer/fifty/#problem-template) for your problem.
Ensure you provide both English and Chinese versions for all sections.
Include clear and detailed solutions, with both analytical and simulation approaches when applicable.
Use code blocks with the exec="true" attribute for runnable Python code.
Place Python code snippets in separate files under the docs/fifty/snippet/ directory and include them using the --8<-- syntax.

Updating Existing Content¶

When updating existing problems or solutions:

Maintain the bilingual format for all sections.
Ensure mathematical correctness in both languages.
Provide clear explanations for both analytical and simulation approaches.
If adding or modifying code implementations, ensure they are correct, efficient, and follow the project's coding style.
Update any related code snippets in the docs/fifty/snippet/ directory.

Testing Locally¶

Before submitting your changes, test them locally using MkDocs:

Make sure you're in the project root directory.
Run the following command to start a local preview server:
```
mkdocs serve
```
Open your web browser and go to http://127.0.0.1:8000/ to view the site.
Make sure your changes appear correctly and don't introduce any errors.

Submitting Your Contribution¶

Commit your changes:

git add .
git commit -m "Your descriptive commit message"

Push your changes to your fork:
```
git push origin your-feature-branch
```
Go to the original Beer repository on GitHub and create a new pull request from your feature branch.
Fill out the pull request template with all relevant information.
Wait for the maintainers to review your pull request. They may ask for changes or clarifications.

Code of Conduct¶

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. You can find the full text of the Code of Conduct in the CODE_OF_CONDUCT.md file.

Thank you for contributing to the Beer project!