Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
291 lines (199 loc) · 9.5 KB

CONTRIBUTING.md

File metadata and controls

291 lines (199 loc) · 9.5 KB
Raw

Contributing to Linkora-socials

First, thank you for considering contributing to Linkora-socials! We welcome contributions to help build out the social primitives, tooling, and ecosystem on Soroban.

This document outlines the development workflow, branching conventions, testing practices, and how to add new contract functions.

Development Workflow

Prerequisites

To get started with local development, ensure you have the following installed:

  • Node.js 18+ (recommended)
  • pnpm 9+
  • Rust toolchain (latest stable)
  • Stellar CLI with Soroban support
  • Docker (required for integration tests)

You can install the Stellar CLI using Cargo:

cargo install --locked stellar-cli

(Note: Depending on your tooling version, soroban-cli may also be valid).

Local Setup

Clone the repository and install the JavaScript workspace dependencies:

git clone git@github.com:Epta-Node/Linkora-social.git
cd Linkora-social
pnpm install

Building Contracts

You can build the Soroban smart contracts from the repository root:

pnpm build:contracts

Alternatively, from within the contracts package:

cd packages/contracts
pnpm build

Testing

We maintain two test suites: unit tests and integration tests.

Running Unit Tests

Unit tests are lightweight, do not require a running network, and often use mocked authorization (mock_all_auths()). They cover core contract logic and state changes.

Run from the repository root:

pnpm --filter contracts test

Or using Cargo directly:

cd packages/contracts
cargo test

Running Integration Tests

Integration tests run against a local Stellar sandbox and use real transaction signing via the CLI. They ensure end-to-end flows (e.g., cross-contract calls, real auth) work as expected.

Run from the repository root:

pnpm test:integration

For more details on sandbox setup, see the Integration Tests README.

First Contribution Walkthrough

1. Fork and Clone

Fork the repository on GitHub, then clone your fork locally.

git clone git@github.com:YOUR-USERNAME/Linkora-social.git
cd Linkora-social

2. Install Dependencies

Install project dependencies and required tooling.

pnpm install
cargo install --locked stellar-cli

3. Verify Setup

Run tests to confirm your setup works.

pnpm --filter contracts test
pnpm test:integration

4. Pick a Good First Issue

Look for issues labeled good first issue or documentation, then comment on the issue before starting.

5. Create a Branch and Make Changes

Create a branch from main, make changes, and rerun tests.

git checkout -b docs/your-change

6. Open a Pull Request

Push your branch and open a pull request against main.

Adding a New Contract Function

When adding a new feature or function to the Linkora contracts, follow these guidelines:

  1. Focus: Ensure the function has a single, clear purpose and falls within the scope of the project.
  2. Access Control: Carefully consider who should be able to call the function and implement the necessary require_auth() checks.
  3. Tests: Every new contract function must be covered by unit tests. If the function introduces a major flow, consider adding or updating an integration test.
  4. Events: New state-changing functions should emit appropriate events to facilitate indexing. Review our event design strategy in EVENTS.md.
  5. Documentation: Add a Rust docstring explaining the inputs, outputs, and authorization rules. Update the API Reference table in the root README.md.

Pull Request Guidelines

We use a standard GitHub flow. Please follow these branching and PR conventions:

  1. Create a branch from main using a descriptive name (e.g., feat/add-xyz, fix/bug-name, docs/update-readme).
  2. Keep changes focused and prefer small pull requests.
  3. Make sure all tests pass locally before opening the PR.
  4. Fill out the Pull Request Template completely.

Contract Versioning Policy

The contract crate version in packages/contracts/contracts/linkora-contracts/Cargo.toml must stay in sync with CHANGELOG.md.

  • Patch bump (x.y.Z): internal fixes that do not change contract interface or behavior expected by integrators.
  • Minor bump (x.Y.z): backward-compatible additions such as new read functions or optional flows.
  • Major bump (X.y.z): breaking changes to function signatures, auth model, storage assumptions, or event contracts.

When a PR changes contract behavior, include a changelog entry and update the crate version in the same PR.

Changelog Format

This project follows Keep a Changelog format for documenting changes.

Changelog Entry Structure

## [Version] - YYYY-MM-DD

### Added
- New features (backward-compatible)
- New contract functions
- New events

### Changed
- Changes to existing functionality (backward-compatible)
- Updates to function behavior
- Improvements to existing features

### Fixed
- Bug fixes
- Security patches
- Error handling improvements

### Deprecated
- Features that will be removed in future versions

### Removed
- Features removed in this version (breaking changes)

### Security
- Security-related changes and vulnerabilities

Version Categories

  • Patch (x.y.Z): Bug fixes, security patches, internal improvements
  • Minor (x.Y.z): New features, backward-compatible changes
  • Major (X.y.z): Breaking changes, removed features, incompatible API changes

Release Process

We provide an automated release script to handle version bumping, changelog updates, and git tagging.

Using the Release Script

  1. Ensure your working directory is clean and you're on the main branch
  2. Run the release script: 
    ./scripts/release.sh
  3. Follow the prompts to enter the new version number
  4. Edit the generated changelog entry with actual changes
  5. Review and push the changes: 
    git diff  # Review changes
git push && git push --tags
  6. Create a GitHub release from the new tag

Manual Release Process

If you prefer to handle releases manually:

  1. Update version in packages/contracts/contracts/linkora-contracts/Cargo.toml
  2. Update version in root package.json
  3. Add changelog entry to CHANGELOG.md
  4. Commit changes with semantic version message: 
    git commit -m "Release X.Y.Z"
  5. Create and push tag: 
    git tag -a "vX.Y.Z" -m "Release X.Y.Z"
git push && git push --tags

Release Script Features

The scripts/release.sh script:

  • Validates semantic version format
  • Checks for existing tags to prevent duplicates
  • Updates versions in both contract and root package files
  • Generates a changelog entry template
  • Creates an annotated git tag
  • Is idempotent for the same version (will fail if tag exists)

PR Checklist

Before submitting or requesting a review, verify the following (as found in our PR template):

  • Tests added or updated for changed behavior
  • Existing tests pass (cargo test and pnpm test:integration)
  • Changes are focused — one concern per PR
  • If a contract function was added or changed, the README API table is updated
  • No unresolved merge conflicts

Branch Protection Policy

The main branch is protected. The following rules are enforced:

  • CI must pass: All pull requests must pass the CI / Unit Tests workflow before they can be merged. This gate exists because unreviewed merges have previously introduced duplicate imports and broken function bodies into main.
  • Review required: At least one approving review from a repository collaborator is required before merge.
  • No direct pushes: Direct pushes to main are restricted to repository administrators. All changes must go through a pull request.
  • No force-pushes: Force-pushing to main is disabled to preserve commit history.

These rules are enforced at the repository level and cannot be bypassed by contributors. If CI fails on your PR, investigate and fix the root cause rather than asking for a merge exemption.

What counts as a CI failure?

The CI / Unit Tests job runs cargo test inside packages/contracts. Your PR will be blocked if:

  • Any unit test panics or returns an unexpected result.
  • The code does not compile (including wasm32v1-none target).

The integration test suite (integration.yml) runs on a nightly schedule and on manual dispatch; it is not a required check for PRs but failures there should still be investigated promptly.

Code Owners

This project uses a CODEOWNERS file to automatically assign reviewers based on the files changed in a pull request.

CODEOWNERS Format

The .github/CODEOWNERS file maps directories to their maintainers:

  • packages/contracts/ → Contract maintainers
  • packages/web/ → Frontend maintainers
  • docs/ → Documentation maintainers
  • .github/ → All maintainers

How to Request Review from Specific Owner

  1. When you create a PR that touches files in the above directories, the corresponding maintainers will be automatically assigned as reviewers.

  2. If you need to request a review from a specific owner, you can mention them in your PR description: @Epta-Node/maintainers please review

  3. For urgent reviews or specific questions, you can also comment on the PR with a mention.

Security

If you discover a security vulnerability, please review our Security Policy for responsible disclosure guidelines. Do not open public issues for security concerns.