Skip to content

docs: add CI pass requirement guidance #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
El-swaggerito merged 2 commits into from
Jul 29, 2026
Merged

docs: add CI pass requirement guidance #137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
35083b9
docs: add CI pass requirement guidance (Closes #115)
Carlys17 Jul 29, 2026
d9b1fac
Merge branch 'main' into docs/ci-pass-requirement-115
El-swaggerito Jul 29, 2026
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
210 changes: 105 additions & 105 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,105 +1,105 @@
# Aegis SDK
The official TypeScript SDK for the **Aegis RWA Protocol**. This library provides a clean, class-based interface to interact with Aegis Soroban smart contracts on the Stellar network.
## Installation
```bash
npm install @aegis/sdk
```
## Quickstart
Initialize the client with a typed environment preset and query the compliance module.
```TypeScript
import { AegisClient } from '@aegis/sdk';
import { Keypair } from '@stellar/stellar-sdk';
const adminKeypair = Keypair.fromSecret('S...');
const aegis = new AegisClient({
environment: 'testnet', // or 'local'; see docs/environments.md
contractId: 'C_YOUR_CONTRACT_ID',
keypair: adminKeypair // Optional for read-only calls
});
async function main() {
// Check if a user is KYC compliant
const isApproved = await aegis.compliance.checkWhitelist('G_USER_PUBLIC_KEY');
console.log('Is User Whitelisted?', isApproved);
}
main();
```
## Role Discovery & Capability Checks
Check what an address is classified as, and what it can currently attempt through the SDK.
This is a client-side convenience for UI gating, not on-chain authorization — see the
[full documentation](./docs/role-discovery.md) for important caveats.
```TypeScript
const roleResult = await aegis.role.discoverRole('G_USER_PUBLIC_KEY');
console.log('Role:', roleResult.role); // 'investor' | 'unauthorized' | 'unknown'
const capability = await aegis.role.checkCapability('G_USER_PUBLIC_KEY', 'receive_transfer');
console.log('Can receive transfer?', capability.isPermitted);
```
## Contract Event Decoder
Decode Soroban contract events into typed audit-trail models for dashboards and indexers.
```typescript
import { decodeContractEvent } from '@aegis/sdk';
const event = decodeContractEvent({
topic: rpcEvent.topic,
value: rpcEvent.value,
txHash: rpcEvent.txHash,
});
if (event.kind === 'transfer') {
console.log(event.from, event.to, event.amount);
}
```
See [Contract Event Decoder](./docs/contract-events.md) for supported topics, unknown fallback behaviour, and dashboard integration guidance.
## Testing
To run the SDK unit tests locally:
```
npm run test
```
Run the full release gate, including TypeScript compilation and browser/Node
runtime compatibility checks:
```bash
npm run check
```
### Pre-submit verification
Run all checks (lint, format, build, test, compat) in a single command before
submitting a PR:
```bash
npm run verify
```
See [Test-First Contribution Guide](docs/test-first-contribution.md) for when behavior changes need happy-path, negative-path, and no-test justification coverage.
See [Verification Command](docs/verification.md) for detailed usage and
troubleshooting guidance.
See [Runtime Compatibility](docs/runtime-compatibility.md) for the supported
environments, what the automated probes cover, and integration guidance.
For step-by-step instructions on reproducing and fixing CI check failures, see the [CI Resolution Workflow](docs/ci-resolution-workflow.md).
## Contributing
We welcome contributions! Please check our [CONTRIBUTING.md](CONTRIBUTING.md) for our branching strategy and code style guidelines.
### Review Process
PRs submitted to this repository are reviewed against our [Pull Request Reviewer Checklist](docs/reviewer-checklist.md), which covers code implementation, unit test coverage, CI build compatibility, API reference documentation, security/compliance, and acceptance criteria.
### Acceptance Criteria Traceability
Every PR **must** include an [acceptance criteria traceability table](docs/acceptance-criteria-traceability.md) that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers.
# Aegis SDK

The official TypeScript SDK for the **Aegis RWA Protocol**. This library provides a clean, class-based interface to interact with Aegis Soroban smart contracts on the Stellar network.

## Installation

```bash
npm install @aegis/sdk
```

## Quickstart
Initialize the client with a typed environment preset and query the compliance module.
```TypeScript
import { AegisClient } from '@aegis/sdk';
import { Keypair } from '@stellar/stellar-sdk';

const adminKeypair = Keypair.fromSecret('S...');

const aegis = new AegisClient({
environment: 'testnet', // or 'local'; see docs/environments.md
contractId: 'C_YOUR_CONTRACT_ID',
keypair: adminKeypair // Optional for read-only calls
});

async function main() {
// Check if a user is KYC compliant
const isApproved = await aegis.compliance.checkWhitelist('G_USER_PUBLIC_KEY');
console.log('Is User Whitelisted?', isApproved);
}

main();
```
## Role Discovery & Capability Checks
Check what an address is classified as, and what it can currently attempt through the SDK.
This is a client-side convenience for UI gating, not on-chain authorization — see the
[full documentation](./docs/role-discovery.md) for important caveats.
```TypeScript
const roleResult = await aegis.role.discoverRole('G_USER_PUBLIC_KEY');
console.log('Role:', roleResult.role); // 'investor' | 'unauthorized' | 'unknown'

const capability = await aegis.role.checkCapability('G_USER_PUBLIC_KEY', 'receive_transfer');
console.log('Can receive transfer?', capability.isPermitted);
```

## Contract Event Decoder
Decode Soroban contract events into typed audit-trail models for dashboards and indexers.

```typescript
import { decodeContractEvent } from '@aegis/sdk';

const event = decodeContractEvent({
topic: rpcEvent.topic,
value: rpcEvent.value,
txHash: rpcEvent.txHash,
});

if (event.kind === 'transfer') {
console.log(event.from, event.to, event.amount);
}
```

See [Contract Event Decoder](./docs/contract-events.md) for supported topics, unknown fallback behaviour, and dashboard integration guidance.

## Testing
To run the SDK unit tests locally:

```
npm run test
```

Run the full release gate, including TypeScript compilation and browser/Node
runtime compatibility checks:

```bash
npm run check
```

### Pre-submit verification

Run all checks (lint, format, build, test, compat) in a single command before
submitting a PR:

```bash
npm run verify
```

See [Test-First Contribution Guide](docs/test-first-contribution.md) for when behavior changes need happy-path, negative-path, and no-test justification coverage.

See [Verification Command](docs/verification.md) for detailed usage and
troubleshooting guidance.

See [Runtime Compatibility](docs/runtime-compatibility.md) for the supported
environments, what the automated probes cover, and integration guidance.

For step-by-step instructions on reproducing and fixing CI check failures, see the [CI Resolution Workflow](docs/ci-resolution-workflow.md).

## Contributing
We welcome contributions! Please check our [CONTRIBUTING.md](CONTRIBUTING.md) for our branching strategy and code style guidelines.

### Review Process
PRs submitted to this repository are reviewed against our [Pull Request Reviewer Checklist](docs/reviewer-checklist.md), which covers code implementation, unit test coverage, CI build compatibility, API reference documentation, security/compliance, and acceptance criteria.

### Acceptance Criteria Traceability
Every PR **must** include an [acceptance criteria traceability table](docs/acceptance-criteria-traceability.md) that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers.

146 changes: 146 additions & 0 deletions docs/ci-pass-requirement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# CI Pass Requirement

> **Applies to:** Aegis SDK (`@aegis/sdk`)
> **Last updated:** 2026-07-29

---

## Overview

All pull requests submitted to the Aegis SDK must pass continuous integration
(CI) checks before they are reviewed or merged. A green CI run is **not
optional** — it is the minimum bar for a contribution to be considered complete.

Failing CI checks block both review and merge. The requirement applies to all
contributors, including first-time contributors and those working on
documentation-only changes.

---

## Why CI Pass Status Matters

### Evaluation Impact

CI status is a primary factor in [GrantFox](https://grantfox.io) compensation
evaluations. A merged PR with unresolved or skipped CI failures will receive
reduced evaluation credit, even if the code changes were accepted. See the
[Contributor Evaluation Policy](./contributor-evaluation-policy.md#33-ci-pipeline-compliance)
for full details.

### Code Quality Gate

The CI pipeline enforces type safety, unit test pass rates, code style
consistency, and runtime compatibility across supported Node.js versions.
Skipping these checks introduces silent regressions that can break downstream
consumers of the SDK.

### Cross-Environment Verification

What works on a contributor's machine may fail on a different Node.js version
or operating system. CI matrix builds (Node 20 and Node 22) catch
environment-specific issues that local testing alone cannot.

---

## CI Checks

The Aegis SDK CI pipeline (`.github/workflows/runtime-compatibility.yml`) runs
the following checks on every pull request:

| Check | Gate | What It Verifies |
| :--- | :--- | :--- |
| **TypeScript Build** | `npm run build` | Compilation succeeds with zero type errors. |
| **Unit Tests** | `npm test` | All Jest test suites pass under `tests/`. |
| **Runtime Compatibility** | `npm run test:compat` | Export probes and runtime checks pass on Node 20 and Node 22. |
| **Linting** | `npm run lint` | ESLint rules are satisfied with no violations. |
| **Code Formatting** | `npm run format` | Prettier formatting rules are applied consistently. |

---

## Common Failure Types

When CI fails, the failure usually falls into one of the categories below.
Each is linked to its resolution guide.

| Failure Type | Symptom | Resolution Guide |
| :--- | :--- | :--- |
| **TypeScript errors** | Build step fails with type mismatch or missing import errors. | [CI Response Guide — Type errors](./ci-response-guide.md#type-errors) |
| **Test failures** | Jest suite fails on one or more assertions. | [CI Response Guide — Test failures](./ci-response-guide.md#test-failures) |
| **Compatibility probe failures** | `test:compat` step fails on export or runtime probes. | [CI Response Guide — Runtime compat failures](./ci-response-guide.md#runtime-compat-failures) |
| **Lint violations** | ESLint reports code style or syntax issues. | [CI Response Guide — Lint failures](./ci-response-guide.md#lint-failures) |
| **Format violations** | Prettier detects unformatted files. | [CI Response Guide — Format failures](./ci-response-guide.md#format-failures) |
| **Dependency issues** | `npm ci` fails during install or script execution. | [CI Response Guide — Dependency issues](./ci-response-guide.md#dependency-issues) |

---

## Verifying CI Locally

Reproduce the full CI gate on your machine before pushing. A passing local run
strongly correlates with a passing CI run.

| Command | What It Checks |
| :--- | :--- |
| `npm run check` | Build + unit tests + runtime compatibility (full release gate). |
| `npm run verify` | Lint + format + build + test + compat (all-in-one pre-submit). |
| `npm run build` | TypeScript compilation only. |
| `npm test` | Unit test suite only. |
| `npm run lint` | ESLint rules only. |

For step-by-step instructions on reproducing and fixing specific failures, see
the [CI Resolution Workflow](./ci-resolution-workflow.md).

---

## Contributor Expectations

### Before Opening a PR

- Run `npm run verify` locally and confirm all steps pass.
- Do not push code that you have not verified locally.
- If a check fails locally, fix it **before** opening the pull request.

### When CI Fails

- Investigate the failure immediately. Click **Details** on the failed GitHub
Actions job to view the output log.
- Fix the root cause — do not skip checks, disable rules, or add `@ts-ignore`
comments to silence failures.
- Push a fix to your branch within a reasonable timeframe. PRs with stale CI
failures may be closed if there is no active communication.

### What Happens If CI Stays Red

| CI Status | Outcome |
| :--- | :--- |
| **Green (all checks pass)** | PR is eligible for review and merge. |
| **Red (one or more failures)** | PR will not be reviewed. Maintainers will wait for a green run. |
| **Red with no update** | PR may be closed after a period of inactivity. |

### If You Are Stuck

Some failures are harder to diagnose than others, especially environment-specific
issues. If you cannot resolve a CI failure:

1. Re-read the failure log carefully — the error message is often enough to
identify the problem.
2. Run the failing command locally with the same Node.js version CI uses
(Node 20 or Node 22).
3. Check [existing issues](https://github.com/AegisRWA/aegis-sdk/issues) for
similar failures and solutions.
4. Open a comment on your PR explaining what you tried and what you observed.
Include a link to the failing CI run.

---

## Related Documentation

- [CI Resolution Workflow](./ci-resolution-workflow.md) — step-by-step procedure
for reproducing and fixing CI failures locally.
- [CI Response Guide](./ci-response-guide.md) — quick reference for diagnosing
and fixing each failure type.
- [PR Evidence Checklist](./pr-evidence-checklist.md) — required evidence for
all pull requests, including CI status verification.
- [Contributor Evaluation Policy](./contributor-evaluation-policy.md) — how CI
status affects GrantFox compensation evaluation.
- [Verification Command](./verification.md) — local `npm run verify` usage and
troubleshooting.
Loading