Skip to content

Contrib and Codebase Guide#

Checkout and push ready#

Fork the Repository

  1. Navigate to https://github.com/jaseci-labs/jaseci
  2. Click the Fork button in the top-right corner
  3. Select your GitHub account to create the fork

Clone and Set Up Upstream

After forking, clone your fork and set up the upstream remote:

# Clone your fork (replace YOUR_USERNAME with your GitHub username)
git clone https://github.com/YOUR_USERNAME/jaseci.git
cd jaseci
git submodule update --init --recursive
git remote add upstream https://github.com/jaseci-labs/jaseci.git
git remote -v

Setting Up Your Dev Envrionment

python3 -m venv .venv
source .venv/bin/activate
pip install -e jac
jac install -e jac-byllm
jac install -e jac-scale
jac install -e jac-client
jac install -e jac-super
jac install -e jac-mcp
pip install pre-commit
pre-commit install
pip install pytest pytest-xdist pytest-asyncio

Run Some Tests

pytest jac -n auto
# See ci jobs in github actions for more stuff to run

Build something awesome, or fix something that's broken

See Rules below. And check .pre-commit-config.yaml to see our lint strategy.

This is how we run the docs.

pip install -e docs # <-- Not a real package more of a script
python docs/scripts/mkdocs_serve.py

Pushing Your First PR

  1. Create a branch, make changes, sync, and push:
git checkout -b your-feature-branch

# Make your changes, then commit
git add .
git commit -m "Description of your changes"

# Keep your fork synced with upstream
git fetch upstream
git merge upstream/main

# Push to your fork
git push origin your-feature-branch
  1. Create a Pull Request:
  2. Go to your fork on GitHub
  3. Click Compare & pull request
  4. Fill in the PR description with details about your changes
  5. Submit the pull request to the main branch of jaseci-labs/jaseci

Tip: PR Best Practices

  • Make sure all pre-commit checks pass before pushing
  • Run tests locally using the test script above
  • Keep your PR focused on a single feature or fix
  • Write clear commit messages and PR descriptions
  • Add a release note fragment (see below)

Adding Release Notes

Every PR that changes package code must include a release note fragment file:

  1. Create a file at docs/docs/community/release_notes/unreleased/<package>/<PR#>.<category>.md
  2. Packages: jaclang, byllm, jac-client, jac-scale, jac-super, jac-mcp
  3. Categories: feature, bugfix, breaking, refactor, or docs

  4. Example: docs/docs/community/release_notes/unreleased/jaclang/1234.bugfix.md

  5. Add one or more bullet points:

- **Fix: Brief title**: Description of what changed.
- **Fix: Another fix in same PR**: Description.

To skip this check, add the skip-release-notes-check label to your PR.

Example PR with a release note fragment: #5573

Code Rules and Guidelines#

Jac Style

All Jac code must follow the project's established coding style. If you're using an AI assistant, prompt it to study the existing style before generating code. For example, when working in a specific area:

"Can you study the jac coding style used in this code base (byllm/project folder), and make sure my change adheres to that style."

No Scaffolding

Never add code that only exists as scaffolding or infrastructure for future PRs. Every line in your PR should serve the change being made right now. The one exception is when two different authors have a producer-consumer dependency for a feature or fix and need to coordinate across PRs.

Type Safety

Write type-safe code. Avoid stringly-typed interfaces:

  • Use enums instead of bare strings for option sets
  • Create named types or dataclasses for complex return values instead of raw tuples like -> tuple[str, str, dict, dict, dict]

Check for Bloat

Before submitting, use an AI assistant to audit your diff for unnecessary code. A good prompt:

"Can you look at the local changes to see if there is any bloat or inefficient implementation given what these changes are achieving."

Issue Assignment

Assignees on GitHub issues means the person is committing to resolve that issue, not that they "should" work on it. Keep as many issues unassigned as possible so contributors can pick them up.

Documentation Updates

The docs site has three tiers with different expectations for contributors:

  • Quick Guide -- Get a quick experience with Jac. Most features don't need to touch this.
  • Full Reference -- Must cover everything. Every feature or change should update the reference docs.

Release Flow (for maintainers)#

Releasing new versions to PyPI is a two-step process using GitHub Actions.

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Create Release PR  │ ─▶ │  Close & reopen PR  │ ─▶ │   Merge to main     │ ─▶ │  Approve & Publish  │
│  (manual trigger)   │    │  (so CI runs) +     │    │  (auto-merge;       │    │  (one-click on the  │
│                     │    │  enable auto-merge  │    │  triggers publish)  │    │  pypi environment)  │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘    └─────────────────────┘

Step 1: Create the Release PR#

  1. Go to GitHub Actions → Create Release PR
  2. Click Run workflow
  3. For each package, select the version bump type (skip, patch, minor, or major):
  4. jaclang, jac-byllm, jac-client, jac-scale, jac-super, jac-mcp, jac-desktop, jaseci
  5. Click Run workflow
  6. The workflow validates versions against PyPI, bumps them, and creates a PR from a release/* branch
  7. Close and reopen the PR to make CI run. The PR is authored by github-actions[bot], and GitHub does not run pull_request checks for PRs opened by the GITHUB_TOKEN actor (workflows triggered by GITHUB_TOKEN can't trigger further workflows, to prevent recursion). Closing and reopening makes the reopen event come from you (a real user), so the PR checks run and attach to the PR. (Permanent fix: author the PR with a GitHub App / PAT token instead.)
  8. Once the checks attach, enable auto-merge on the PR
  9. When CI passes, the PR auto-merges to main (or approve and merge it manually)

Step 2: Approve Publishing#

After the release PR is merged, the Publish Release workflow triggers automatically:

  1. It parses the packages and versions from the PR title
  2. Manual approval required (only maintainers with pypi environment access can approve):
  3. Go to GitHub Actions → find the running Publish Release workflow
  4. The workflow will pause at the "approve-release" job waiting for approval
  5. Click on the job, then click Review deployments
  6. Select the pypi environment and click Approve and deploy
  7. The workflow then handles everything automatically:
  8. Builds all packages once (precompiling bytecode for packages that need it)
  9. Publishes in dependency order (tiered):
    • Tier 1: jaclang (base package; everything depends on it)
    • Tier 2: jac-byllm, jac-client, jac-scale, jac-super, jac-mcp (depend only on jaclang)
    • Tier 3: jac-desktop (depends on a tier-2 plugin, jac-client)
    • Tier 4: jaseci (meta-package; depends on everything above)
  10. Pushes git tags ({package}-v{version}, plus v{version} for jaseci)
  11. Creates a GitHub Release with artifacts
  12. Builds standalone binaries (if jaseci was released)

Note: The workflow waits for each tier on PyPI before publishing the next, so a package never lands before a dependency it pins. Tiers are configured per package in scripts/release_utils.jac.

Troubleshooting#

Issue Solution
CI checks not running / not showing on the release PR Expected: GitHub skips pull_request checks for PRs opened by the github-actions[bot] / GITHUB_TOKEN actor. Close and reopen the PR so the reopen event comes from a real user, and the checks then run and attach. (A GitHub App / PAT token authoring the PR would remove this step.)
Auto-merge won't enable / PR won't merge Auto-merge needs the PR's required status checks to be attached; do the close/reopen above first so the checks exist on the PR
Publish workflow didn't trigger Ensure the PR branch started with release/
A tier failed to publish Re-run the failed job from GitHub Actions; already-published packages are skipped (skip-existing)
Need to re-publish after the release PR is merged Manually trigger Publish Release (workflow_dispatch) and check the packages to publish
Version conflict on PyPI The Create Release PR workflow validates this upfront - if you hit this, someone manually published