# Publishing Quickstart for Open Source Projects

This is the shortest path from "code and big files on my machine" to "a public release anyone can browse and download, without an account." It is the open-source walkthrough of [Publishing Releases](https://swarmfile.com/docs/guides/publishing-releases) - read that for every knob; this page is the ten-minute version.

What you get:

- A **public project page** at `/public/<org-slug>/<project-slug>`: rendered README, file browser, previews, release history, contributors, and a download button.
- **Downloads that need no account.** Visitors browse, preview and stream byte ranges anonymously; each file or source-archive download passes a quick one-time proof-of-work check (a few milliseconds in the browser) that makes bulk scraping expensive. Attached release assets are direct anonymous links. Egress is free and unmetered on every plan.
- **Explore and community surfaces**: a listing on [Explore](https://swarmfile.com/explore) once a release is ready, optional topics and website on the project's profile, follow-by-email and an Atom feed for new releases, stars from signed-in visitors, and optional public Issues and Discussions.
- **A Free plan that needs no card** for public projects, with a flat 5 GiB of storage. Private and encrypted projects start on a paid plan. An established open-source project can also apply for a [Verified OSS grant](https://swarmfile.com/docs/guides/public-projects-and-org-profiles#verified-oss-grants) (the Pro plan at no cost).

What to expect: Swarmfile is not a full forge (no project boards, milestones or code intelligence), but a public project gets a light issue tracker you can turn on, search inside the latest release's text files, and a fork-to-upstream proposal flow that lands as an ordinary merge request in the upstream project. Git `clone` and fast-forward `push` work when the project has git access enabled.

## 1. Create a public project

In the web app, **New project → Visibility: public**. Choose an organization slug and project slug - they become the public URL and the git/LFS path, so pick names you're happy to keep. On a brand-new org, keep the default plaintext tier; a public project must be plaintext (managed encryption is for private work).

No organization yet? Sign up, create one, and stay on the Free plan - public projects are free.

## 2. Get your files in

Pick whichever fits your repo:

- **From your machine**: install the desktop app, mount the project, and copy files onto the drive ([Getting Started](https://swarmfile.com/docs/guides/getting-started)). Saves stream in the background.
- **From an existing git repository**: `swarmfile git import` brings the whole repository in with its history, branches and tags:

  ```bash
  swarmfile git import https://github.com/you/your-project.git
  ```

  It defaults to a new project named after the repository; `--name`/`--org` override, and `--into <org>/<project>` retries a partial import. Fidelity limits are in [Known Limitations](https://swarmfile.com/docs/reference/known-limitations#importing-an-existing-repository-converts-or-skips-some-git-shapes).
- **Keep your repo where it is and send only the big files**: point `git-lfs` at Swarmfile and keep source on your existing host ([Git-LFS](https://swarmfile.com/docs/guides/git-lfs)):

  ```bash
  git config lfs.url https://hub.swarmfile.com/orgs/<org>/lfs/<project>
  ```

Whatever the path, use `.swarmfile/publicignore.yml` to keep private paths out of a release **before** you tag (see step 4).

## 3. Tag what you're shipping

A release always publishes a **tag**, and a tag names one commit. Commit the state you want (on the drive, via `swarmfile commit` / `swarmfile tag create`, or via `git push` if git access is on), then:

```bash
swarmfile tag create v1.0
```

`swarmfile tag` never moves an existing tag (a forced `git push` can). Once a tag is published as a release, treat it as permanent.

## 4. Publish the release

The web **Releases** tab has a publish wizard with a preflight; the CLI is the same thing:

```bash
swarmfile release preflight v1.0   # exactly what would publish; exits non-zero if it can't
swarmfile release create v1.0      # publish
swarmfile release list             # pending → ready (or failed, with a reason)
```

The preflight shows the files and total size, anything `.swarmfile/publicignore.yml` keeps out, and any tracked paths your ignore files hide from the browser but would still publish. A new release starts **pending** while the download archive builds, then becomes **ready**. If a publish failed permanently, tag a new commit and publish that - re-running `release create` on the same tag does nothing.

## 5. Attach build artifacts

Compiled binaries don't belong in the tagged tree. Attach them to the release instead:

```bash
swarmfile release attach v1.0 dist/your-tool-1.0-macos-arm64.tar.gz
```

Or drag them into the release's **Assets** dialog in the web app. Files over 100 MiB attach with the CLI. Assets are served anonymously on their own rate-limited bucket - unlike release files, they carry no proof-of-work challenge (they're plain download links, which is what package managers and install scripts need) - and the member Releases tab shows a per-asset download count plus a per-path download-activity panel.

## 6. Polish the public page

An owner or admin sets what the public page shows from the dashboard's **Projects** list: the project's menu has **Add description** (or **Edit description**) for the description and **Edit public profile** for topics, website and funding links (more in [Public Projects & Org Profiles](https://swarmfile.com/docs/guides/public-projects-and-org-profiles)). The Files tab opens on the release's README, with Issues / Discussions / Releases alongside it, and the org profile at `/public/<org-slug>` collects your public projects.

## 7. Keep the door open for contributors

- **Follow / Atom feed**: visitors can subscribe to release emails with the **Follow releases** button (a verified account) or the feed at `/public/<org-slug>/<project-slug>/releases.xml`.
- **git** (if enabled in project settings): `git clone swarmfile://<org>/<project>` gives the full history; fast-forward `git push` sends commits back. The public page shows the release's commit history too.
- **Requests in**: a signed-in visitor can request comment or contributor access from the public page; approved contributors upload into the project's `Contributions` folder, and neither uses a seat ([Requesting access](https://swarmfile.com/docs/guides/public-projects-and-org-profiles#requesting-access)).
- **Forks**: **Copy** in the project actions copies the release into another org. The copy's public page links back with **Forked from**.
- **Issues and Discussions**: turn on **Public issues** and **Public discussions** in **Project settings** → **Public page** (both off by default). Anyone can read them; posting takes a free account with a verified email. See [Issues](https://swarmfile.com/docs/guides/public-projects-and-org-profiles#issues).
- **Contributions back**: an owner or admin of a fork picks a branch in project settings' **Propose to upstream** card and sends it. The branch is copied into the upstream project as a temporary `contrib/…` branch (a single flattened commit, up to 512 MiB) and reviewed there as an ordinary merge request. The upstream decides, and a proposal never merges itself. The upstream controls who may propose with its **Cross-project contributions** setting: **Off** (the default), **Proposals** (a direct fork's owner or admin may send one), or **Open** (also a fork of a fork, up to five hops away).
- **Funding**: add up to five funding links (Open Collective or any `https://` link) under the project's menu → **Edit public profile** in the dashboard's **Projects** list, and the public page shows a **Sponsor** button beside Follow.

## 8. Mirror to GitHub Releases (optional)

If the project is linked to a GitHub repo (the GitHub App), the repo row's **Mirror releases** checkbox mirrors each future ready release there - tag, notes and attached assets. It is off by default, one-way (GitHub-side edits are never imported), and unpublishing a release here deletes its mirrored GitHub release. A CI-driven team can instead paste a workflow that calls the project's mirror endpoint on `release: published` (see [Git-LFS → Mirror releases](https://swarmfile.com/docs/guides/git-lfs)); both routes run the same idempotent mirror, so either can be safely re-run.

## 9. What's deliberately not built

Named so you can decide with the real picture: Issues are deliberately light (no boards, milestones, attachments or author edits); content search covers the latest release's text files only, not every branch; `git push` is fast-forward only, annotated tags and octopus merges are refused, and git access is off by default (turn it on per project); public projects are plaintext. The [Known Limitations](https://swarmfile.com/docs/reference/known-limitations) page keeps the full list.