Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ GraalPy is a Python 3.12 compliant runtime.
It has first-class support for embedding in Java and can turn Python applications into fast, standalone binaries.
GraalPy is ready for production running pure Python code and has experimental support for many popular native extension modules.

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).

If you’re considering contributing to this repository, you need to sign the [Oracle Contributor Agreement](https://www.graalvm.org/community/contributors/) before we can merge your changes.
Also, review the [Code of Conduct](https://www.graalvm.org/community/conduct/) for contributors.

[![Contributing to Graalpy](https://img.youtube.com/vi/qeAUgXQR1h0/0.jpg)](https://www.youtube.com/watch?v=qeAUgXQR1h0)

## Why GraalPy?

**Low-overhead integration with Java and other languages**
Expand Down Expand Up @@ -209,13 +218,6 @@ General documentation about [polyglot programming](https://www.graalvm.org/lates

The best way to get in touch with us is to join the `#graalpy` channel on [GraalVM Slack][slack] or [tweet us][twitter].

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md).

If you're thinking about contributing something to this repository, you will need to sign the [Oracle Contributor Agreement](https://www.graalvm.org/community/contributors/) for us to able to merge your work.
Also take a look at the [code of conduct](https://www.graalvm.org/community/conduct/) for contributors.

## Security

Consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process.
Expand Down
99 changes: 99 additions & 0 deletions docs/contributor/GETTING_STARTED.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Contributing to GraalPy: getting started

Thanks for considering contributing to GraalPy.
This page aims at helping you through your first contribution to the project.

For deep technical details and complete command references, see [CONTRIBUTING.md](./CONTRIBUTING.md).

If you want help while getting started, join the [GraalVM community Slack](https://www.graalvm.org/slack-invitation/).

## Quick path for your first contribution

1. [Pick an issue](#1-pick-an-issue)
2. [Set up your environment](#2-set-up-your-environment)
3. [Make a change](#3-make-a-change)
4. [Run focused checks](#4-run-focused-checks)
5. [Open your Pull Request](#5-open-your-pull-request)

---

## 1. Pick an issue

Start with something small and well-scoped, for instance, issues labeled [good first issue](https://github.com/oracle/graalpython/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22).

If there is no issue yet, create one from the [issue templates](https://github.com/oracle/graalpython/issues/new/choose) so the work is tracked and discussed.

![Issue Form](/docs/contributor/assets/issue_form_selector.png)

If you think you've found a security vulnerability, do not raise a GitHub issue and follow the instructions in our [security policy](https://github.com/oracle/graalpython/blob/master/SECURITY.md).

## 2. Set up your environment

You can contribute using one of the following environments:

- **GitHub Codespaces** (quickest onboarding): see [Using a GitHub codespace](./CONTRIBUTING.md#using-a-github-codespace)
- **Your local machine**: see [Setting up on your machine](./CONTRIBUTING.md#setting-up-on-your-machine)

Then do the minimal Git setup:

```bash
git checkout master
git pull
git checkout -b <your-branch-name>
```

Optionally, after setup:

```bash
mx ideinit
```

## 3. Make a change

Keep your first change small and easy to review (one issue, one objective, one PR).
Before editing, quickly identify where the code or tests live by checking the project structure in the
[Development Layout](https://github.com/oracle/graalpython/blob/master/docs/contributor/CONTRIBUTING.md#development-layout).

If you use GitHub Codespaces with GitHub Copilot Pro, you can also run an AI coding agent in an isolated environment with access to Issues, PRs, and CI context.

## 4. Run focused checks

Before opening a PR, run tests affected by your changes.

Common commands:

- `mx clean`: clean build files
- `mx build`: build GraalPy
- `mx python-svm`: build GraalPy native
- `mx gate --tags python-unittest`: Python unit tests
- `mx gate --tags python-junit`: Java/JUnit tests
- `mx graalpytest <path>::<test-name>`: run one targeted Python test

Example:

```bash
mx graalpytest graalpython/lib-python/3/test/test_threading.py::test.test_threading.ExceptHookTests.test_excepthook
```

If you need a complete list of commands, run `mx help` or check [CONTRIBUTING.md](./CONTRIBUTING.md).

## 5. Open your pull request

1. Push your branch to your fork
2. Open a PR against `master`
3. Mark it **Ready for review** when it is ready

Important:

- You must sign the [Oracle Contributor Agreement (OCA)](https://www.graalvm.org/community/contributors/) before merge
- CI unit tests run when the PR is ready for review (not in draft)
- Opening a PR early in your fork is fine if you want CI feedback

---

## What to read next

After your first contribution, continue with:

- [CONTRIBUTING.md](./CONTRIBUTING.md) for full setup, workflows, and CI details
- [IMPLEMENTATION_DETAILS.md](./IMPLEMENTATION_DETAILS.md) for deeper architecture context
Binary file added docs/contributor/assets/issue_form_selector.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading