marco-trest-test/docs/trest-onboarding.md

TREST Onboarding Guide (Private Repo)

This guide is designed for a new joiner to quickly set up access, install, and understand usage of the private trest package hosted at:

• https://gitea.jig.com.hk/jig-software/trest

Because the repository is private, this guide uses a secure workflow that works in most teams.

1) Access Prerequisites

Make sure you have:

• A working company VPN connection (if required by network policy).
• A Gitea account with access to jig-software/trest.
• A Personal Access Token (PAT) in Gitea with at least repository read scope.
• Git installed locally.

Quick checks:

git --version
ssh -T git@gitea.jig.com.hk

If SSH is not configured yet, follow section 2.

2) Set Up Git Access

Choose one method.

Option A: SSH (recommended)

1. Generate a key if you do not already have one:

ssh-keygen -t ed25519 -C "your.name@company.com"

2. Start agent and add key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

3. Copy and add your public key to Gitea:

cat ~/.ssh/id_ed25519.pub

4. Test auth:

ssh -T git@gitea.jig.com.hk

Option B: HTTPS + PAT

Use HTTPS clone and enter your username + PAT when prompted.

git clone https://gitea.jig.com.hk/jig-software/trest.git

3) Clone and Inspect the Repository

git clone git@gitea.jig.com.hk:jig-software/trest.git
cd trest

Collect quick project facts:

ls -la
find . -maxdepth 2 -type f | head -50

Identify the ecosystem from marker files:

• package.json -> Node.js package
• pyproject.toml or setup.py -> Python package
• Cargo.toml -> Rust crate
• go.mod -> Go module

4) Install Runtime and Dependencies

Use the matching path below.

If trest is Node.js

If your team distributes trest through Gitea Packages (npm registry), configure Yarn auth first.

If Yarn is new to you, read docs/yarn-basics-cheatsheet.md first.

Yarn 4 + Gitea Registry Setup

This workspace already uses a scoped registry in .yarnrc.yml.

Required scope assumptions:

• Scope: @jig-software
• Registry URL: https://gitea.jig.com.hk/api/packages/jig-software/npm/

Set your token in the current shell:

export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"

Verify package access (recommended):

yarn npm info @jig-software/trest

Optional identity check (only if your Gitea npm endpoint supports whoami):

yarn npm whoami --scope jig-software

If package info is returned, install trest:

yarn add @jig-software/trest

If package naming differs, discover the exact name from your team or the Gitea Packages page, then run yarn add <exact-package-name>.

Fallback: Install Directly From Gitea Git

Use this when trest exists as a private repository but is not published in Gitea Packages npm.

SSH form:

yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git

HTTPS form:

yarn add trest@git+https://gitea.jig.com.hk/jig-software/trest.git

Pin to a branch, tag, or commit for reproducibility:

yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git#main

node -v
npm -v
npm ci
npm test

Yarn note:

• This repo uses Plug'n'Play (nodeLinker: pnp). If a tool expects node_modules, you can switch linker mode for that project.

If trest is Python

python3 --version
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pytest -q

If trest is Rust

rustc --version
cargo --version
cargo test

If trest is Go

go version
go test ./...

5) Understand Package Usage Quickly

Work top-down with this sequence:

1. Read README.md and docs/ first.
2. Find entry points:
   • Node: main, exports, src/index.*
   • Python: package __init__.py, public modules
   • Rust: src/lib.rs, src/main.rs
   • Go: exported symbols in key package files
3. Locate examples/tests to learn intended behavior.
4. Build a tiny local consumer project and call the simplest public API.

Search commands:

rg "example|usage|quick start|getting started|test" -n .
rg "export|public|def |class |func " -n src tests .

6) Create a Minimal Consumer Sandbox

In a separate directory, create a tiny app that imports trest and performs one happy-path call.

Suggested structure:

sandbox/
  README.md
  <language standard files>
  smoke_test.*

Your first smoke test should validate:

• Package can be installed or linked.
• Import works.
• One primary API call returns expected output.
• Error handling behavior for invalid input is understood.

7) Team Questions to Ask Early

Ask these within your first day to avoid drift:

• Which branch/tag/version should new projects consume?
• Is there a compatibility matrix (runtime versions, OS, architecture)?
• What APIs are stable vs experimental?
• Any required env vars, secrets, or service dependencies?
• Preferred testing strategy for downstream consumers?

8) Troubleshooting

• 404/auth failures: confirm VPN, permissions, token scope, and clone URL.
• SSL/cert issues: check corporate certificate installation and git SSL settings.
• Install failures: pin runtime version from project config files (.nvmrc, pyproject, etc.).
• Test failures: run a single test first, then expand scope.

9) Onboarding Completion Checklist

You are done when all are true:

• Can clone jig-software/trest locally.
• Can install dependencies successfully.
• Can run test suite (or at least smoke tests).
• Can explain top 3 public APIs in your own words.
• Have written notes on setup steps and pitfalls for the team.