Development Workflows

Common development workflows and automation helpers for the OneKey monorepo.

Quick Reference

Task	Command	Description
Lint all files	yarn lint:only	Full project lint
Lint staged files	yarn lint:staged	Pre-commit: only modified files
Type check	yarn tsc:only	Full project type check
Type check (staged)	yarn tsc:staged	Pre-commit type check
Create test version	See upgrade-test-version.md	Manual workflow

Lint Commands

See: references/rules/fix-lint.md

Lint All Files

yarn lint:only

Lint Staged Files (Pre-commit)

# Only lint files that are staged for commit - fast!
yarn lint:staged

Type Check

# Full project type check
yarn tsc:only

# Same as above, for pre-commit use
yarn tsc:staged

Note: TypeScript requires full project context and cannot check individual files.

Common Lint Fixes

// Unused variable → prefix with _
const { used, unused: _unused } = obj;

// Unused parameter → prefix with _
function foo(used: string, _unused: number) {}

Pre-commit Workflow

Before committing:

1. yarn lint:staged - Lint only modified files (fast)
2. yarn tsc:staged - Type check (if needed)
3. Ensure changes are properly staged

For quick pre-commit validation:

# Quick: lint only
yarn lint:staged && git commit -m "your message"

# Thorough: lint + type check
yarn lint:staged && yarn tsc:staged && git commit -m "your message"

Test Version Creation

See: references/rules/upgrade-test-version.md

For QA upgrade testing with version pattern 9XXX.YY.Z.

Build number formula:

DATE=$(date +%Y%m%d)
BUILD_NUMBER=$((${DATE}00 + 30))

Files to modify:

• .env.version
• .github/actions/shared-env/action.yml
• .github/workflows/release-android.yml
• apps/mobile/android/app/build.gradle

Key Files

Purpose	File
Lint config	.oxlintrc.json
Spellcheck skip list	development/spellCheckerSkipWords.txt
Version config	.env.version
Build config	apps/mobile/android/app/build.gradle

Related Skills

• /1k-git-workflow - Git branching and commit conventions
• /1k-coding-patterns - Code style and patterns

---

Referenced Files

The following files are referenced in this skill and included for context.

references/rules/upgrade-test-version.md

# Creating Upgrade Test Version

Automates the creation of test version branches with hardcoded build configurations for testing app upgrade functionality and version migration flows.

## Workflow

### Step 1: Gather Version Information

Ask the user for the test version number using AskUserQuestion:

Question: "What test version number should be used?" Options:

• "9005.20.0" (example format)
• Custom input

The version should follow the pattern `9XXX.YY.Z` where:
- `9XXX` indicates a test version (e.g., 9005)
- `YY.Z` matches the production version being tested

### Step 2: Calculate Build Number

Calculate the build number as: **current date (YYYYMMDD) + "00" suffix + 30**

The build number must be 10 digits in format: `YYYYMMDD00 + 30 = YYYYMMDD30`

Example: If today is `20260113`, the build number is `2026011300 + 30 = 2026011330`

```bash
# Calculate build number (10 digits)
DATE=$(date +%Y%m%d)
BUILD_NUMBER=$((${DATE}00 + 30))
echo "Build number: $BUILD_NUMBER"  # Output: 2026011330

Step 3: Create and Checkout Branch

Create a new branch named after the test version:

git checkout -b <test_version>
# Example: git checkout -b 9005.20.0

Step 4: Modify Configuration Files

Modify the following files in order:

4.1 Update .env.version

Change the VERSION field to the test version:

VERSION=<test_version>
BUNDLE_VERSION=1

4.2 Update .github/actions/shared-env/action.yml

In the "Setup ENV BUILD_NUMBER" steps, replace ALL build number logic with a hardcoded value. Remove the if/else conditions and simplify to:

- name: Setup ENV BUILD_NUMBER
  shell: bash
  run: |
    echo "BUILD_NUMBER=<calculated_build_number>" >> $GITHUB_ENV

Remove both:

• "Setup ENV BUILD_NUMBER to 1" step
• "Setup ENV BUILD_NUMBER by workflow_run" step

Replace with single step that hardcodes the build number.

4.3 Update .github/workflows/release-android.yml

In the "Write .env.version" step, change:

echo "BUILD_NUMBER=${{ env.BUILD_NUMBER }}" >> .env.version

To:

echo "BUILD_NUMBER=<calculated_build_number>" >> .env.version

4.4 Update apps/mobile/android/app/build.gradle

In the defaultConfig block, update:

versionCode <calculated_build_number>
versionName "<test_version>"

Example:

versionCode 2026011330
versionName "9005.20.0"

Step 5: Commit and Push

git add -A
git commit -m "chore: prepare test version <test_version> with build number <build_number>"
git push -u origin <test_version>

File Locations Summary

File	Change
.env.version	Update VERSION
.github/actions/shared-env/action.yml	Hardcode BUILD_NUMBER, remove conditionals
.github/workflows/release-android.yml	Hardcode BUILD_NUMBER in .env.version write
apps/mobile/android/app/build.gradle	Update versionCode and versionName

Validation Checklist

Before pushing, verify:

• Branch name matches test version
• .env.version VERSION field updated
• Build number conditionals removed from shared-env
• Build number hardcoded in release-android workflow
• versionCode is numeric (build number)
• versionName is quoted string (test version)

### references/rules/fix-lint.md

```markdown
# Fix Lint

Helps fix oxlint warnings in the OneKey app-monorepo codebase.

**IMPORTANT**: This project uses **oxlint** (not ESLint). The active linting configuration is in `.oxlintrc.json`.

## Lint Commands

### Lint All Files
```bash
yarn lint:only

Lint Staged Files (Pre-commit)

# Only lint files staged for commit - fast for pre-commit checks
yarn lint:staged

Type Check

# Full project type check
yarn tsc:only

# Same as above, for pre-commit use
yarn tsc:staged

Note: TypeScript requires full project context and cannot check individual files.

Usage

Use this when:

• Running yarn lint and encountering warnings
• Cleaning up code before committing
• Fixing spellcheck, unused variable, or other linting warnings

Workflow

Step 1: Run Lint and Analyze Warnings

yarn lint:only 2>&1 | tail -100

Step 2: Categorize Warnings

Warnings typically fall into these categories:

Category	Rule	Fix Strategy
Spellcheck	@cspell/spellchecker	Add to skip list or fix typo
Unused vars	@typescript-eslint/no-unused-vars	Remove import or prefix with _
Non-null assertion	@typescript-eslint/no-non-null-assertion	Add type guard or cast
Nested components	react/no-unstable-nested-components	Extract component
Import order	import/order	Fix import ordering

Step 3: Fix Each Category

Spellcheck Warnings (@cspell/spellchecker)

1. Evaluate the word: Is it a legitimate technical term or a typo?

2. For legitimate technical terms, add to skip list:

   # File: development/spellCheckerSkipWords.txt
   # Add the word on a new line at the end of the file
   newTechnicalTerm
   

3. For known typos that can't be fixed (e.g., in translation keys), add with a comment above:

   # Known typo - exsited -> existed (ETranslations.some_key)
   exsited
   

4. Common legitimate terms to add:

   • Build tools: chunkhash, minimizer, rspack
   • Blockchain: lovelace, Kusama, workchain, feebump
   • UI: Virtualized, overscan, overscrolling
   • Crypto: nacl, Bech32, secp256k1

Unused Variable Warnings (@typescript-eslint/no-unused-vars)

1. Unused imports - Remove the import:

   // Before
   import { Used, Unused } from 'package';
   // After
   import { Used } from 'package';
   

2. Unused function parameters - Prefix with underscore:

   // Before
   function foo(used: string, unused: number) { return used; }
   // After
   function foo(used: string, _unused: number) { return used; }
   

3. Unused destructured variables - Prefix with underscore:

   // Before
   const { used, unused } = obj;
   // After
   const { used, unused: _unused } = obj;
   

4. Unused assigned variables - Prefix with underscore:

   // Before
   const unused = getValue();
   // After
   const _unused = getValue();
   

Non-null Assertion Warnings (@typescript-eslint/no-non-null-assertion)

Add type assertions or guards:

// Before
const value = obj.prop!.name;
// After
const value = (obj.prop as { name: string } | undefined)?.name;

Nested Component Warnings (react/no-unstable-nested-components)

Extract the component outside the parent:

// Before
function Parent() {
  const NestedComponent = () => <div />;
  return <NestedComponent />;
}

// After
const ExtractedComponent = () => <div />;
function Parent() {
  return <ExtractedComponent />;
}

Step 4: Verify Fixes

yarn lint:only 2>&1 | tail -50

Pre-commit Workflow

For fast pre-commit validation, only lint modified files:

# Lint only staged files
yarn lint:staged

# Then commit
git commit -m "your message"

# Or combine
yarn lint:staged && git commit -m "your message"

# With type check
yarn lint:staged && yarn tsc:staged && git commit -m "your message"

Common Patterns in This Codebase

Translation Key Typos

Translation enum keys (e.g., ETranslations.perp_invaild_tp_sl) cannot be easily renamed as they're managed externally. Add to skip list with a comment:

# Known typo in translation key - invaild -> invalid
invaild

Provider API Methods

Methods like openInMobileApp that throw NotImplemented() often have unused parameters:

public async openInMobileApp(
  _request: IJsBridgeMessagePayload,
  _params: ISignMessagePayload,
): Promise<void> {
  throw new NotImplemented();
}

Destructuring from Hooks

When destructuring from hooks but not using all values:

const { used, unused: _unused } = usePromiseResult(...);

Tips

1. Check if word is in skip list before adding:

   grep -i "wordToCheck" development/spellCheckerSkipWords.txt
   

2. Verify no regressions after fixes:

   yarn tsc:only
   

Key Files

• development/spellCheckerSkipWords.txt - Add technical terms and known typos
• .oxlintrc.json - Linting configuration