> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

# Contributing Guide

> How to contribute to the App Store Connect CLI project

Thanks for your interest in contributing to the App Store Connect CLI! This guide will help you get started with development, testing, and submitting contributions.

## Development Setup

### Requirements

* **Go 1.26 or higher**
* Git
* (Optional) macOS for keychain integration testing

### Clone and Build

Clone the repository and build the CLI:

```bash theme={null} theme={null}
git clone https://github.com/rorkai/App-Store-Connect-CLI.git
cd App-Store-Connect-CLI
make build
```

This creates the `asc` binary in the current directory.

### Run Tests

Run the test suite:

```bash theme={null} theme={null}
go test ./...
```

**Important**: Always use keychain bypass when running tests to avoid macOS keychain prompts:

```bash theme={null} theme={null}
ASC_BYPASS_KEYCHAIN=1 make test
```

### Optional Tooling

Install development tools:

```bash theme={null} theme={null}
make tools   # Installs gofumpt + golangci-lint
make lint    # Uses golangci-lint if installed, else go vet
make format  # gofmt + gofumpt (requires gofumpt)
```

## Integration Tests (Opt-in)

Integration tests hit the real App Store Connect API and are **skipped by default**.

To run integration tests, set credentials in your environment:

```bash theme={null} theme={null}
export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"
export ASC_APP_ID="YOUR_APP_ID"

make test-integration
```

### Headless Alternative

For CI/CD or headless environments, use base64-encoded keys:

```bash theme={null} theme={null}
export ASC_PRIVATE_KEY_B64="BASE64_ENCODED_KEY"
```

## Local API Testing (Optional)

If you have App Store Connect API credentials, you can run real API calls locally:

```bash theme={null} theme={null}
export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"
export ASC_APP_ID="YOUR_APP_ID"

asc testflight feedback list --app "$ASC_APP_ID"
asc testflight crashes list --app "$ASC_APP_ID"
asc reviews --app "$ASC_APP_ID"
```

### Credential Storage

Credentials are stored:

1. **macOS**: System keychain (when available)
2. **Fallback**: Config file at `~/.asc/config.json` (restricted permissions)
3. **Repo-local**: `./.asc/config.json` (also supported)

**Important**: Do not commit secrets or `.p8` files to the repository.

## Local Validation

Run this checklist **before opening a PR**:

```bash theme={null} theme={null}
make tools               # Install gofumpt + golangci-lint
make format              # Format code
make lint                # Lint code
make check-command-docs  # Verify command docs are up to date
ASC_BYPASS_KEYCHAIN=1 make test  # Run tests (bypasses keychain)
make build               # Build binary
./asc --help             # Smoke-test the binary
```

### Command Documentation

If you changed command/help text, regenerate documentation:

```bash theme={null} theme={null}
make generate-command-docs  # Updates docs/COMMANDS.md
make check-command-docs     # Verifies docs are current
```

Commit `docs/COMMANDS.md` if it changed.

## Pull Request Guidelines

### Before Opening a PR

1. **Keep PRs small and focused**: One logical change per PR
2. **Add or update tests**: Cover new behavior and edge cases
3. **Update README**: If behavior or scope changes
4. **Avoid committing credentials**: No API keys or `.p8` files
5. **Run validation**: Complete the local validation checklist above

### PR Checklist

* [ ] Code formatted (`make format`)
* [ ] Linting passes (`make lint`)
* [ ] Tests pass (`ASC_BYPASS_KEYCHAIN=1 make test`)
* [ ] Command docs updated (`make generate-command-docs`)
* [ ] Build succeeds (`make build`)
* [ ] README updated (if needed)
* [ ] No secrets committed

### Pre-commit Hook

Install local pre-commit hook to enforce checks automatically:

```bash theme={null} theme={null}
make install-hooks
```

This runs formatting, linting, and doc checks before each commit.

### PR Description

Include in your PR description:

* **What**: What does this PR do?
* **Why**: Why is this change needed?
* **How**: How does it work?
* **Testing**: Commands run and key scenarios validated
* **Breaking changes**: Note any backward-incompatible changes

## Development Workflow

### Git Workflow

1. **Fork** the repository
2. **Create a branch** from `main`:
   ```bash theme={null} theme={null}
   git checkout -b feature/my-feature
   ```
3. **Make changes** and commit:
   ```bash theme={null} theme={null}
   git add .
   git commit -m "feat: add new feature"
   ```
4. **Push** to your fork:
   ```bash theme={null} theme={null}
   git push origin feature/my-feature
   ```
5. **Open a PR** against `main`

### Commit Message Style

Follow conventional commit format:

* `feat:` - New feature
* `fix:` - Bug fix
* `refactor:` - Code refactoring
* `test:` - Test additions/changes
* `docs:` - Documentation changes
* `chore:` - Maintenance tasks

**Example**:

```
feat(builds): add PKG upload support

- Use com.apple.pkg UTI for PKG files
- Add validation for PKG file format
- Update upload timeout defaults
```

## Testing Discipline

### Test-Driven Development (TDD)

For bugs, refactors, and new features:

1. **Start with a failing test** that captures expected behavior
2. **Implement** the fix or feature
3. **Verify** the test passes
4. **Refactor** if needed

### Test Coverage

For new features:

* **CLI-level tests**: Flags, output, errors, exit codes
* **Unit tests**: Core logic and edge cases
* **Integration tests** (optional): Real API calls

### Test Patterns

Test realistic CLI invocation patterns:

```bash theme={null} theme={null}
# Flags before subcommands
asc --profile prod builds list --output json

# Flag values that look like subcommands
asc --profile list apps list

# Multiple flags with values
asc --profile prod builds list --limit 5 --output json
```

For more details, see `docs/TESTING.md`.

## CLI Implementation Checklist

When adding new commands:

* [ ] Register in `internal/cli/registry/registry.go`
* [ ] Set `UsageFunc: shared.DefaultUsageFunc`
* [ ] Use `shared.ContextWithTimeout` for HTTP requests
* [ ] Validate required flags and test error messages
* [ ] Add `internal/cli/cmdtest` coverage
* [ ] Use `httptest` for network payload tests
* [ ] Update help text and examples

## Architecture Guidelines

### Architecture-First Development

Before implementing new commands/flags, produce a design note:

1. **Command placement** in existing taxonomy
2. **OpenAPI endpoint/schema** validation
3. **UX shape**: Flags, output formats, exit codes
4. **Backward compatibility** and deprecation impact
5. **Test plan**: RED → GREEN approach

If command shape is ambiguous, align before coding.

### Command Lifecycle

User-facing commands/flags follow lifecycle states:

* `experimental` - Early development, may change
* `stable` - Production-ready, backward compatible
* `deprecated` - Scheduled for removal, migration path provided
* `removed` - No longer available

Do not delete stable commands directly. Deprecate first with:

* Warning text in help/output
* Tests covering old and new behavior
* Changelog entry with upgrade path

## Security

### Reporting Security Issues

**Do NOT open public GitHub issues** for security vulnerabilities.

Report privately using GitHub Security Advisories:
[https://github.com/rorkai/App-Store-Connect-CLI/security/advisories/new](https://github.com/rorkai/App-Store-Connect-CLI/security/advisories/new)

If you can't use GitHub Security Advisories, contact the maintainer:
[https://github.com/rudrankriyam](https://github.com/rudrankriyam)

### What to Include

* Clear description of vulnerability and potential impact
* Steps to reproduce (proof-of-concept if possible)
* Affected versions and platforms (macOS/Linux, Go version, etc.)

### Supported Versions

Security updates are provided for:

* Latest stable release
* `main` branch

## Wall of Apps

Wall content is generated by `make update-wall-of-apps`. The generator reads `docs/wall-of-apps.json` and updates the Wall snippet in `README.md`.

### Add Your App

1. **Fork** the repository
2. **Run**:
   ```bash theme={null} theme={null}
   make generate app APP="Your App Name" LINK="https://apps.apple.com/app/id1234567890" CREATOR="your-github-handle" PLATFORM="iOS,macOS"
   ```
   This updates `docs/wall-of-apps.json` and syncs `README.md` in one step.
3. **Alternative**: Edit `docs/wall-of-apps.json` directly, then run:
   ```bash theme={null} theme={null}
   make update-wall-of-apps
   ```
4. **Commit** all generated changes:
   * `docs/wall-of-apps.json`
   * `README.md`
5. **Open a PR**

### Format

```json theme={null} theme={null}
{
  "app": "Your App Name",
  "link": "https://apps.apple.com/app/id1234567890",
  "creator": "your-github-handle",
  "platform": ["iOS"]
}
```

Platform values are free-form labels: `iOS`, `macOS`, `watchOS`, `tvOS`, `visionOS`, `Android`, `Web`.

**Note**: If you only change the Wall table in `README.md` without updating `docs/wall-of-apps.json`, CI will fail the Wall generation check.

## Additional Resources

### Documentation

* `docs/GO_STANDARDS.md` - Go coding standards
* `docs/TESTING.md` - Testing patterns and conventions
* `docs/CONTRIBUTING.md` - Detailed CLI development notes
* `docs/API_NOTES.md` - API quirks and behaviors
* `CONTRIBUTING.md` - This guide (root)

### API Reference

* OpenAPI snapshot: `docs/openapi/latest.json`
* Endpoint index: `docs/openapi/paths.txt`
* API docs: [https://sosumi.ai/documentation/appstoreconnectapi/](https://sosumi.ai/documentation/appstoreconnectapi/)

## Getting Help

If you need help:

1. **Check existing issues**: [https://github.com/rorkai/App-Store-Connect-CLI/issues](https://github.com/rorkai/App-Store-Connect-CLI/issues)
2. **Read documentation**: Command reference, API notes, testing guide
3. **Ask in discussions**: Open a GitHub discussion
4. **Open an issue**: If you've found a bug or have a feature request

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

## Code of Conduct

Please review and follow the [Code of Conduct](https://github.com/rorkai/App-Store-Connect-CLI/blob/main/CODE_OF_CONDUCT.md).

## Thank You!

Contributions of all sizes are appreciated. Whether it's fixing typos, reporting bugs, or implementing features, every contribution helps make the CLI better for everyone.