Publishing Ingots

Sharing your Fe ingots allows others to build on your work. This guide covers best practices for preparing and publishing ingots.

Preparing for Publication

Before publishing, ensure your ingot is ready:

1. Complete fe.toml Metadata

[ingot]
name = "my_awesome_lib"
version = "1.0.0"

Use semantic versioning:

• Major (1.0.0 → 2.0.0): Breaking changes
• Minor (1.0.0 → 1.1.0): New features, backwards compatible
• Patch (1.0.0 → 1.0.1): Bug fixes, backwards compatible

2. Clean Public API

Export only what users need in src/lib.fe:

// Export public items
pub use token::Token
pub use token::Transfer
pub use token::Approval

// Internal helpers stay private (no pub)
use internal::validate_amount

3. Document Your Code

Add comments explaining public items:

/// A standard ERC20 token implementation.
///
/// Supports transfer, approve, and transferFrom operations.
pub contract Token {
    // ...
}

/// Transfer tokens from the caller to a recipient.
///
/// Emits a Transfer event on success.
pub fn transfer(to: Address, amount: u256) {
    // ...
}

Publishing via Git

The most common way to share ingots is through git repositories:

1. Create a Repository

Host your ingot on GitHub, GitLab, or another git host:

git init
git add .
git commit -m "Initial release v1.0.0"
git remote add origin https://github.com/you/my-ingot.git
git push -u origin main

2. Share the Dependency Line

After pushing, get the commit hash and share it with users:

git rev-parse HEAD
# Output: a1b2c3d4e5f6789...

Tell users how to add your ingot:

[dependencies]
my_awesome_lib = { source = "https://github.com/you/my-ingot.git", rev = "0123456789abcdef0123456789abcdef01234567" }

Note: rev must be the full 40-character commit hash printed by git rev-parse HEAD. Abbreviated hashes, tags, and branch names are rejected; the exact commit is what makes builds reproducible without lock files.

Repository Structure

A well-organized published ingot:

my-ingot/
├── fe.toml
├── README.md           # Usage instructions
├── LICENSE             # License file
└── src/
    ├── lib.fe          # Public exports
    └── ...             # Implementation

Versioning Guidelines

When to Bump Versions

Change Type	Version Bump	Example
Bug fix	Patch	1.0.0 → 1.0.1
New feature (compatible)	Minor	1.0.0 → 1.1.0
Breaking change	Major	1.0.0 → 2.0.0

What Counts as Breaking

• Removing public items
• Changing function signatures
• Changing struct field types
• Renaming public items

What’s Not Breaking

• Adding new public items
• Internal implementation changes
• Performance improvements

Best Practices

Use Descriptive Names

Choose a name that clearly indicates what your ingot does:

# Good
name = "erc20_token"
name = "access_control"

# Less clear
name = "utils"
name = "helpers"

Reference Dependencies by Commit

Every git dependency, including those of a published ingot, must name a full commit hash:

[dependencies]
# Valid - full 40-character commit hash
base_lib = { source = "https://github.com/org/base.git", rev = "0123456789abcdef0123456789abcdef01234567" }

# Invalid - branch names, tags, and abbreviated hashes are rejected
base_lib = { source = "https://github.com/org/base.git", rev = "main" }

Include Examples

Show users how to use your ingot in your README:

## Usage

Add to your `fe.toml`:

\`\`\`toml
[dependencies]
my_lib = { source = "https://github.com/you/my-lib.git", rev = "0123456789abcdef0123456789abcdef01234567" }
\`\`\`

Then import and use:

\`\`\`fe
use my_lib::Token

contract MyContract {
    // ...
}
\`\`\`

Summary

Step	Action
Prepare	Complete metadata, clean API, add docs
Version	Use semantic versioning
Publish	Push to git, tag releases
Share	Provide dependency line for users