Skip to content

Commit

Permalink
Merge branch 'main' into critical-systems-thinking
Browse files Browse the repository at this point in the history
  • Loading branch information
@jtorreggiani
jtorreggiani authored Oct 26, 2024
2 parents 113a07d + a789d4a commit 13b1927
Show file tree
Hide file tree
Showing 2 changed files with 194 additions and 13 deletions.
144 changes: 144 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# Contributing

We welcome Pull Requests for general contributions. Please read the [code of conduct](CODE_OF_CONDUCT.md) before contributing. If you have a larger new feature or any questions on how to develop a fix, we recommend you open an [issue][issues] before starting. We recommend reading the [Goose docs on plugins](https://block-open-source.github.io/goose/plugins/plugins.html) for more information about how plugins work.

## Prerequisites

Goose uses [uv][uv] for dependency management, and formats with [ruff][ruff].
Make sure you have installed `uv` to install dependencies and run commands from within goose and the goose-plugins repositories.

## Getting Started

[Fork][fork] the repositories and clone to your local machine.

```sh
git clone https://github.com/block/goose
git clone https://github.com/block-open-source/goose-plugins
```

Create the virtual environment in each repository using `uv`.

```sh
uv sync
uv venv
```

Run the `source ... activate` command that is output by the `uv venv` command

### Install Goose Plugins to your local goose environment

Now that you have a local environment, you can install goose-plugins to your local environment in editable mode. This allows you to make changes to the plugins and see them reflected in your local goose. From within your goose repository, run the following command:

```
uv add --editable ~/path/to/goose-plugins
```

Run goose via `uv run` to iteratively develop your plugin

```sh
uv run goose session start
```

### Run Tests

To run the test suite against your edges, use `pytest`:

```sh
uv run pytest tests -m "not integration"
```

or use `just`

```sh
just test
```

## Opening a Pull Request

1. Create a new branch for your changes:

```sh
git checkout -b feature/your-feature-name
```

2. Make your changes and ensure all tests pass:

```sh
uv run pytest tests
```

3. Format your code using ruff:

```sh
uv run ruff format .
```

4. Commit your changes following the [Conventional Commits](#conventional-commits) specification:

```sh
git commit -m "feat: add new feature"
```

5. Push your changes to your fork:

```sh
git push origin feature/your-feature-name
```

6. Visit the original repository on GitHub and click "New Pull Request"

7. Select your fork and the feature branch containing your changes

8. Fill out the pull request template with:

- A clear title following Conventional Commits
- A description of your changes
- Any related issues
- Testing steps
- Screenshots (if applicable)

9. Submit the pull request and wait for review

10. Address any feedback or requested changes from maintainers

## Evaluations

Given that so much of Goose involves interactions with LLMs, our unit tests only go so far to confirming things work as intended.

We're currently developing a suite of evaluations, to make it easier to make improvements to Goose more confidently.

In the meantime, we typically incubate any new additions that change the behavior of the Goose through **opt-in** plugins - `Toolkit`s, `Moderator`s, and `Provider`s. We welcome contributions of plugins that add new capabilities to _goose_. We recommend sending in several examples of the new capabilities in action with your pull request.

Additions to the [developer toolkit][developer] change the core performance, and so will need to be measured carefully.

## Conventional Commits

This project follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for PR titles. Conventional Commits make it easier to understand the history of a project and facilitate automation around versioning and changelog generation.

Common types include:

- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation changes
- `test:` for adding or modifying tests
- `chore:` for routine tasks and maintenance

## Release

In order to release a new version of goose, you need to do the following:

1. Update version in `pyproject.toml` for `goose` and package dependencies such as `exchange`
2. Create a PR and merge it into main branch

This repo has a GitHub action that will automatically create a new release and publish the package to PyPI. These packages are not considered stable and are not recommended for production use.

[issues]: https://github.com/block/goose/issues
[goose-plugins]: https://github.com/block-open-source/goose-plugins
[ai-exchange]: https://github.com/block/goose/tree/main/packages/exchange
[developer]: https://github.com/block/goose/blob/dfecf829a83021b697bf2ecc1dbdd57d31727ddd/src/goose/toolkit/developer.py
[uv]: https://docs.astral.sh/uv/
[ruff]: https://docs.astral.sh/ruff/
[just]: https://github.com/casey/just
[adding-toolkit]: https://block.github.io/goose/configuration.html#adding-a-toolkit
[goose-docs]: https://block.github.io/goose/
[fork]: https://github.com/block/goose/fork
63 changes: 50 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Community plugins repository for [Goose][goose] 🧩
# Community plugins repository for [Goose][goose] 🧩

<p align="center">
<img src="docs/assets/goose_plugins_repository.png" alt="Goose Plugins Repository" width="500"/>
<img src="docs/assets/goose_plugins_repository.png" alt="Goose Plugins Repository" width="500"/>
</p>


## 🎉 Hacktoberfest 2024 🎉

`goose-plugins` is a participating project in Hacktoberfest 2024! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone.

### To get started:

1. Read the [contributing guide](https://github.com/square/goose-plugins/blob/main/CONTRIBUTING.md).
2. Read the [code of conduct](https://github.com/square/goose-plugins/blob/main/CODE_OF_CONDUCT.md).
3. Choose a task from this project's Hacktoberfest issues in [here](https://github.com/square/goose-plugins/issues) and follow the instructions. Each issue has the 🏷️ `hacktoberfest` label.
Expand All @@ -20,48 +20,85 @@ Have questions? Connecting with us in our [Discord community](https://discord.gg

## Installation

Goose plugins are currently only available by cloning this repository and linking to your local version of Goose. Installation via a package manager is being investigated. Keep an eye out for updates!

These instructions assume have cloned the Goose repository and the Goose plugins repository and are able to run goose running via `uv run goose`.

1. List the current toolkits available

```sh
pipx install goose-plugins --include-deps
uv run goose toolkit list
```

To check that the plugins are installed, run
2. Install the goose community plugins in editable mode

```sh
goose toolkit list
uv add --editable ~/path/to/goose-plugins
```

You should see the `artify` plugin in the list of available toolkits.
3. List the toolkits again to see the new plugins

```sh
uv run goose toolkit list
```

You should see the community plugins in the list of available toolkits.

4. Add the plugin to your Goose configuration file

Then to run Goose,
Update your config at `~/.config/goose/profile.yaml` to include the plugin you want to use.

```yaml
default:
provider: anthropic
processor: claude-3-5-sonnet-20240620
accelerator: claude-3-5-sonnet-20240620
moderator: truncate
toolkits:
- name: developer
requires: {}
- name: your_community_plugin
requires: {}
```
5. Start a new goose session and your plugin should be available.
```sh
goose session start
uv run goose session start
```

## Developing Plugins

[Check out the Goose docs on plugins!](https://block-open-source.github.io/goose/index.html)
Check out the [Goose docs on plugins!](https://block-open-source.github.io/goose/plugins/plugins.html) for more information on developing plugins.

1. [Fork][fork] the repositories and clone to your local machine.

1. Clone the goose-plugins-exemplar repository and the goose repository
```sh
git clone https://github.com/block-open-source/goose
git clone https://github.com/block/goose
git clone https://github.com/block-open-source/goose-plugins
```
2. Create the virtual environment for Goose in the Goose repo

2. Create the virtual environment in each repository using `uv`.

```sh
uv sync
uv venv
```

Run the `source ... activate` command that is output by the `uv venv` command

3. Install the goose community plugins in editable mode

```sh
uv add --editable ~/path/to/goose-plugins
```

4. Run goose via `uv run` to iteratively develop your plugin

```sh
uv run goose session start
```

[goose]: https://github.com/square/goose
[goose-docs]: https://square.github.io/goose/plugins.html
[fork]: https://github.com/block-open-source/goose-plugins/fork

0 comments on commit 13b1927

Please sign in to comment.