Release Process

This page documents how releases are managed for Nexgent.

Note: Releases are performed exclusively by Nexgent maintainers. This documentation is provided for transparency so contributors understand how their merged PRs make it into releases.

Versioning

Nexgent follows Semantic Versioning (opens in a new tab):

MAJOR.MINOR.PATCH

1.0.0 → 1.0.1 (patch: bug fixes)
1.0.0 → 1.1.0 (minor: new features, backwards compatible)
1.0.0 → 2.0.0 (major: breaking changes)

Version Examples

Change	Version Bump	Example
Bug fix	Patch	`1.0.0` → `1.0.1`
New feature	Minor	`1.0.0` → `1.1.0`
Breaking API change	Major	`1.0.0` → `2.0.0`
Security fix	Patch	`1.0.0` → `1.0.1`

Release Schedule

Release Type	Frequency	Description
Patch	As needed	Bug fixes, security patches
Minor	Monthly	New features, improvements
Major	As needed	Breaking changes

Security patches are released immediately regardless of schedule.

Release Workflow

The following steps are performed by Nexgent maintainers when preparing a release.

1. Prepare Release

# Ensure main is up to date
git checkout main
git pull origin main
 
# Create release branch
git checkout -b release/v1.2.0

2. Update Version

Update version in all package.json files:

// Root package.json
{
  "version": "1.2.0"
}
 
// packages/backend/package.json
{
  "version": "1.2.0"
}
 
// packages/frontend/package.json
{
  "version": "1.2.0"
}
 
// packages/shared/package.json
{
  "version": "1.2.0"
}

3. Update Changelog

Add entry to CHANGELOG.md:

## [1.2.0] - 2024-01-15
 
### Added
- Webhook signature verification (#123)
- DCA mode templates (#125)
 
### Changed
- Improved stop loss calculation performance (#127)
 
### Fixed
- Fixed balance not updating after trade (#124)
 
### Security
- Updated dependencies to patch vulnerabilities

4. Create Pull Request

git add .
git commit -m "chore: prepare release v1.2.0"
git push origin release/v1.2.0

Open PR to merge release/v1.2.0 into main.

5. Merge and Tag

After PR approval:

# Merge to main
git checkout main
git merge release/v1.2.0
git push origin main
 
# Create tag
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

6. Create GitHub Release

Go to GitHub Releases
Click "Draft a new release"
Select tag v1.2.0
Title: v1.2.0
Copy changelog entry to description
Publish release

Changelog Format

Entry Format

- Brief description of change (#issue-number)
- Another change with @contributor credit (#456)

Breaking Changes

Breaking changes require:

Major version bump
Migration guide in release notes
Deprecation notice in previous minor release (when possible)

Migration Guide Example

## Migration Guide: v1.x to v2.0
 
### Breaking Changes
 
#### API Changes
 
**Before (v1.x):**
```typescript
await agentService.create({ name, walletAddress });

After (v2.0):

await agentService.create({ 
  name, 
  walletAddress,
  tradingMode: 'simulation', // Now required
});

Deprecated Features Removed

agent.balance property removed (use balanceService.get())
/api/v1/legacy/* endpoints removed


---

## Hotfix Process

For critical bugs in production, maintainers follow an expedited release process:

### 1. Create Hotfix Branch

```bash
git checkout main
git checkout -b hotfix/v1.2.1

2. Apply Fix

Make minimal changes to fix the issue.

3. Fast-Track Review

Request expedited review
Focus on the specific fix
Skip non-essential CI checks if needed

4. Release

# Merge and tag
git checkout main
git merge hotfix/v1.2.1
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git push origin main --tags

Pre-Release Versions

For testing before official release:

1.2.0-alpha.1   # Alpha (unstable)
1.2.0-beta.1    # Beta (feature complete, testing)
1.2.0-rc.1      # Release candidate (final testing)

Creating Pre-Release

git tag -a v1.2.0-beta.1 -m "Pre-release v1.2.0-beta.1"
git push origin v1.2.0-beta.1

Mark as "Pre-release" on GitHub Releases.

Docker Images

Docker images are published on release:

Tag	Description
`latest`	Latest stable release
`v1.2.0`	Specific version
`v1.2`	Latest patch in minor
`v1`	Latest in major

Release Checklist

Before Release

Release

PR merged to main
Git tag created
GitHub Release published
Docker images published

After Release

Verify deployment (if applicable)
Announce release
Monitor for issues

Pull Request Process Glossary