Contributing through a lane

You can send a change to any public repository on GitStack, even one you can't write. Your stacks go to your own lane, shown as @you/branch. Maintainers review it like any other stack and land it for you.

Install gs and sign in#

curl -fsSL https://gitstack.sh/install.sh | sh
gs login

Getting Started has the other ways to install.

Clone, commit, submit#

gs clone acme/payments
cd payments
gs switch -c fix-typo
# edit files
gs add README.md
gs commit -m "docs: fix the typo in the intro"
gs review create -t "docs: fix the typo in the intro"
gs submit

gs clone sees that you can't write the repository and sets the clone up to push your stacks to your lane. gs submit sends the stack for review and prints a link to each review. A stack can hold several reviews, as it does for anyone else: see Stacks & navigation.

A plain git push to a branch is refused with a hint to run gs submit.

Agree to the CLA#

Some repositories ask contributors to agree to a contributor license agreement before their changes land. gs submit tells you when one does and prints the review page to agree on. You can also read it and agree from the terminal:

gs cla
gs cla agree

The land checks each of your commits by its author email, so commit with an email of your GitStack account or your noreply address: your GitHub noreply address when your account is connected to GitHub, or <handle>@users.noreply.gitstack.sh. The review page links to the emails your account has. To fix a commit, set the email and run gs amend --reset-author --no-edit, then gs push.

When the repository changes its CLA, you are asked to agree again.

While it is in review#

• Comments, LGTMs and requested changes arrive on the review page, as they do for any review.
• A maintainer may push to your lane to fix something up. Their patchset is recorded as theirs. gs sync takes it when you have nothing unpushed; otherwise it names their patchset and stops, and gs sync --take-remote takes it, keeping your commits under refs/gitstack/backup/.
• You can't run CI on a lane yourself. The maintainer's land runs the repository's required checks first.

When it lands#

A maintainer lands your stack onto the base branch. Each landed commit keeps you as its author. Once the whole stack has landed, the server removes your lane.

You can have up to 10 open lanes in a repository, holding up to 50 MiB of changes that have not landed. Abandoning a lane's reviews (gs review abandon) frees it. Accounts in their first week can push 20 times and comment 20 times a day.

If you get write access#

Once a maintainer gives you write access, gs submit says so. Run gs lane leave and new branches push as ordinary branches. Stacks already in your lane stay there.

What maintainers do#

Maintainers see open contributions in their Queue. They check a lane out, review it and land it:

gs checkout @eve/fix-typo
gs submit

Taking contributions covers the rest.