PACKAGE_MANAGEMENT

Package Management Guide

This guide covers how to upload packages to various registries using GitHub Commander.

Overview

GitHub Commander supports uploading packages to:

• npm (JavaScript/Node.js)
• PyPI (Python)
• Cargo (Rust)
• And other package registries

Packages Panel Interface

The Packages Panel includes:

• Package Type Selection - Choose the registry (npm, pip, cargo)
• Folder Selection - Browse to package folder
• Registry URL - Configure registry endpoint
• Upload Button - Initiate package upload
• Status Display - Show upload progress and results

Uploading npm Packages

Prerequisites

Before uploading to npm:

• Have an npm account
• Be logged in to npm locally or have authentication token
• Package must have valid package.json
• Package name must be unique (or you must own it)

Uploading to npm

1. Select a repository
2. Go to the Packages Panel
3. Select "npm" as the package type
4. Click "Browse..." to select the package folder
5. Enter the npm registry URL (default: https://registry.npmjs.org)
6. Click "Upload Package"
7. The package will be published to npm

Package Requirements

Valid npm packages must have:

• package.json with:
• name - Unique package name
• version - Semantic version
• description - Package description
• main - Entry point file
• keywords - Search terms (optional)
• author - Author information (optional)
• license - License information (optional)

Authentication

npm authentication requires:

• Local npm login: npm login
• Or authentication token in .npmrc
• Token must have publish permissions

Private Registries

To use a private npm registry:

1. Enter custom registry URL
2. Configure authentication for that registry
3. Ensure you have publish permissions

Uploading Python Packages

Prerequisites

Before uploading to PyPI:

• Have a PyPI account
• Enable 2FA on PyPI (required)
• Generate API token for uploads
• Package must have valid structure

Uploading to PyPI

1. Select a repository
2. Go to the Packages Panel
3. Select "pip" as the package type
4. Click "Browse..." to select the package folder
5. Enter the PyPI repository URL (default: https://pypi.org/simple)
6. Click "Upload Package"
7. The package will be published to PyPI

Package Requirements

Valid Python packages must have:

• setup.py or pyproject.toml
• README.md or README.rst
• LICENSE file
• Proper package structure:
  package-name/ ├── setup.py ├── README.md ├── LICENSE └── package_name/ ├── __init__.py └── module.py

Authentication

PyPI authentication requires:

• API token from PyPI account settings
• Token stored in ~/.pypirc or environment variable
• Or username/password (deprecated, use token instead)

Test PyPI

To test uploads before production:

1. Use Test PyPI URL: https://test.pypi.org/simple
2. Separate account for Test PyPI
3. Verify package works before publishing to PyPI

Uploading Cargo Packages

Prerequisites

Before uploading to crates.io:

• Have a crates.io account
• Generate API token
• Package must have valid Cargo.toml

Uploading to crates.io

1. Select a repository
2. Go to the Packages Panel
3. Select "cargo" as the package type
4. Click "Browse..." to select the package folder
5. Click "Upload Package"
6. The package will be published to crates.io

Package Requirements

Valid Rust packages must have:

• Cargo.toml with:
• name - Unique package name
• version - Semantic version
• authors - Author list
• description - Package description
• license - License information
• repository - Repository URL (optional)
• src/ directory with main.rs or lib.rs

Authentication

Cargo authentication requires:

• API token from crates.io
• Token stored in ~/.cargo/credentials
• Login with cargo login

Registry Configuration

Default Registries

• npm: https://registry.npmjs.org
• PyPI: https://pypi.org/simple
• Test PyPI: https://test.pypi.org/simple
• crates.io: https://crates.io

Custom Registries

To use a custom registry:

1. Select the package type
2. Enter custom registry URL
3. Configure authentication for that registry
4. Ensure you have publish permissions

Private Registries

For private registries:

1. Obtain registry URL from your organization
2. Configure authentication credentials
3. Set registry URL in the panel
4. Upload as normal

Package Versioning

Semantic Versioning

Follow semantic versioning (SemVer):

• MAJOR.MINOR.PATCH (e.g., 1.2.3)
• Increment MAJOR for incompatible changes
• Increment MINOR for new features (backwards compatible)
• Increment PATCH for bug fixes (backwards compatible)

Pre-release Versions

Use pre-release identifiers:

• 1.0.0-alpha
• 1.0.0-beta.1
• 1.0.0-rc.1

Version Conflicts

If package name exists:

• You must own the package
• Or use a different name
• Or use scoped packages (npm): @username/package-name

Troubleshooting

"Failed to upload package"

Common causes:

• Invalid authentication
• Package name already exists
• Invalid package structure
• Network issues

Solutions:

• Verify authentication credentials
• Check package name availability
• Validate package structure
• Ensure internet connection

"Package name already exists"

Solutions:

• Use a different package name
• Or if you own it, update version
• For npm, use scoped packages

"Invalid package structure"

Solutions:

• Verify required files exist
• Check configuration file syntax
• Ensure proper directory structure
• Validate with registry tools locally

Authentication Errors

Solutions:

• Verify API token is valid
• Check token permissions
• Ensure token is for correct registry
• Regenerate token if necessary

Best Practices

Before Uploading

1. Test package locally
2. Run all tests
3. Update documentation
4. Verify version number
5. Check CHANGELOG

Package Quality

• Write comprehensive documentation
• Include examples
• Add tests
• Use semantic versioning
• Keep dependencies updated
• Respond to issues and PRs

Security

• Don't commit secrets
• Use environment variables
• Keep dependencies secure
• Review third-party code
• Use vulnerability scanners

Next Steps

After managing packages, explore:

• Release Management - Create GitHub releases
• Git Operations - Version control your packages