diff --git a/python/README.md b/python/README.md index 5b012ff60bf..afe1800878c 100644 --- a/python/README.md +++ b/python/README.md @@ -36,8 +36,10 @@ To create a pull request (PR), ensure the following checks are met. You can run - Test: `poe test` - Mypy: `poe mypy` - Pyright: `poe pyright` -- Build docs: `poe --directory ./packages/autogen-core/ docs-build` -- Auto rebuild+serve docs: `poe --directory ./packages/autogen-core/ docs-serve` +- Proto: `poe gen-proto` +- Clean and Build docs: `poe doc-clean && poe doc-build` +- Auto rebuild+serve docs: `poe docs-serve` + Alternatively, you can run all the checks with: - `poe check` diff --git a/python/packages/autogen-core/docs/src/development/contributing.md b/python/packages/autogen-core/docs/src/development/contributing.md new file mode 100644 index 00000000000..5a8b84bf4e1 --- /dev/null +++ b/python/packages/autogen-core/docs/src/development/contributing.md @@ -0,0 +1,34 @@ +# Contributing to AutoGen + +The project welcomes contributions from developers and organizations worldwide. Our goal is to foster a collaborative and inclusive community where diverse perspectives and expertise can drive innovation and enhance the project's capabilities. Whether you are an individual contributor or represent an organization, we invite you to join us in shaping the future of this project. Possible contributions include but not limited to: + +- Pushing patches. +- Code review of pull requests. +- Documentation, examples and test cases. +- Readability improvement, e.g., improvement on docstr and comments. +- Community participation in [issues](https://github.com/microsoft/autogen/issues), [discussions](https://github.com/microsoft/autogen/discussions), and [twitter](https://twitter.com/pyautogen). +- Tutorials, blog posts, talks that promote the project. +- Sharing application scenarios and/or related research. + +Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit . + +If you are new to GitHub [here](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/) is a detailed help source on getting involved with development on GitHub. + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## Roadmaps + +To see what we are working on and what we plan to work on, please check our +[Roadmap Issues](https://aka.ms/autogen-roadmap). + +## Becoming a Reviewer + +There is currently no formal reviewer solicitation process. Current reviewers identify reviewers from active contributors. diff --git a/python/packages/autogen-core/docs/src/development/contributing_environment.md b/python/packages/autogen-core/docs/src/development/contributing_environment.md new file mode 100644 index 00000000000..aa7e5634808 --- /dev/null +++ b/python/packages/autogen-core/docs/src/development/contributing_environment.md @@ -0,0 +1,57 @@ +# Setup Local Development Environment + +## Create a fork of AutoGen +You will need your own copy of AutoGen (aka fork) to work on the code. Go to the AutoGen [project page](https://github.com/microsoft/autogen) and hit the Fork button. You will want to clone your fork to your machine + +```sh +git clone https://github.com/your-user-name/autogen.git autogen-yourname +cd autogen-yourname +git remote add upstream https://github.com/microsoft/autogen.git +git fetch upstream +``` + +This creates the directory autogen-yourname and connects your repository to the upstream (main project) AutoGen repository. + +## Install uv +`uv` is a package manager that assists in creating the necessary environment and installing packages to run AutoGen. + +You can install it with `pipx install uv` or `pip install uv`, or other [installation methods](https://docs.astral.sh/uv/getting-started/installation/). + +## Create a Virtual Environment +During development, you may need to test changes made to any of the packages.\ +To do so, create a virtual environment where the AutoGen packages are installed based on the current state of the directory.\ +Run the following commands at the root level of the `python` directory, i.e., `autogen-yourname/python`: + +```sh +uv sync --all-extras +source .venv/bin/activate +``` +- `uv sync --all-extras` will create a `.venv` directory at the current level and install packages from the current directory along with any other dependencies. The `all-extras` flag adds optional dependencies. +- `source .venv/bin/activate` activates the virtual environment. + +## Common Tasks before making a PR +To create a pull request (PR), ensure the following checks are met. You can run each check individually: +- Format: `poe format` +- Lint: `poe lint` +- Test: `poe test` +- Mypy: `poe mypy` +- Pyright: `poe pyright` +- Proto: `poe gen-proto` +- Clean and Build docs: `poe doc-clean && poe doc-build` +- Auto rebuild+serve docs: `poe docs-serve` + +Alternatively, you can run all the checks with: +- `poe check` + +> [!NOTE] +> These need to be run in the virtual environment. + +### Creating a New Package + +To create a new package, similar to `autogen-core` or `autogen-chat`, use the following: + +```sh +uv sync +source .venv/bin/activate +cookiecutter ./templates/new-package/ +``` diff --git a/python/packages/autogen-core/docs/src/development/index.md b/python/packages/autogen-core/docs/src/development/index.md new file mode 100644 index 00000000000..8778eda11d7 --- /dev/null +++ b/python/packages/autogen-core/docs/src/development/index.md @@ -0,0 +1,15 @@ +--- +myst: + html_meta: + "description lang=en": | + Development Guide for AutoGen, a framework for building multi-agent applications with AI agents. +--- + +# Development + +```{toctree} +:maxdepth: 1 + +contributing +contributing_environment +``` diff --git a/python/packages/autogen-core/docs/src/index.md b/python/packages/autogen-core/docs/src/index.md index bee058bd912..956f9dc5f19 100644 --- a/python/packages/autogen-core/docs/src/index.md +++ b/python/packages/autogen-core/docs/src/index.md @@ -105,4 +105,5 @@ Get Started user-guide/index packages/index reference/index +development/index ``` diff --git a/python/pyproject.toml b/python/pyproject.toml index 3b099db535e..3a3f0fa2ed4 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -75,7 +75,9 @@ lint = "python run_task_in_pkgs_if_exist.py lint" pyright = "python run_task_in_pkgs_if_exist.py pyright" mypy = "python run_task_in_pkgs_if_exist.py mypy" test = "python run_task_in_pkgs_if_exist.py test" - -check = ["fmt", "lint", "pyright", "mypy", "test"] - +doc-clean = "poe --directory ./packages/autogen-core/ docs-clean" +doc-build = "poe --directory ./packages/autogen-core/ docs-build" +doc-serve = "poe --directory ./packages/autogen-core/ docs-serve" gen-proto = "python -m grpc_tools.protoc --python_out=./packages/autogen-core/src/autogen_core/application/protos --grpc_python_out=./packages/autogen-core/src/autogen_core/application/protos --mypy_out=./packages/autogen-core/src/autogen_core/application/protos --mypy_grpc_out=./packages/autogen-core/src/autogen_core/application/protos --proto_path ../protos/ agent_worker.proto --proto_path ../protos/ cloudevent.proto" + +check = ["fmt", "lint", "pyright", "mypy", "test", "gen-proto", "doc-clean", "doc-build", "doc-serve"]