# Contributing to Lisa #
Currently Lisa lives in roughly 4 different places, all of which have a unique 'piece of the
puzzle' for Lisa:
- Issue Tracking Lives in Codeberg: <https://codeberg.org/rem-verse/lisa/issues>
- A mirror of the source code lives in Codeberg for discovery: <https://codeberg.org/rem-verse/lisa>
- The 'source of truth' for the source code, and all changes that are reviewed live in Gerrit: <https://gerrit.miku.build/q/project:rem-verse/lisa>
- All CI Jobs, and artifacts for Lisa live on buildkite: <https://buildkite.com/miku-dot-build/rem-verse-lisa>
## Contributing an Issue/Feature Request ##
Go to the codeberg issues page, and file an issue, and it will be
triaged/acted-on by maintainers. Please use the most relavent issue template
for your particular issue, and don't worry about getting it wrong.
## Contributing Code to Lisa ##
> NOTE: This guide assumes you've logged into gerrit.miku.build, and setup an
> SSH key.
Contributing Code to Lisa, is different than most other projects, because all
of our changes go through gerrit, which admittedly doesn't have the best UX for
newcomers who are used to GitHub style workflows. There are lots of benefits
with gerrit, and to be honest one of the [great walkthroughs for setting gerrit up
is done by Lix](https://wiki.lix.systems/books/lix-contributors/page/gerrit)
since they also use Gerrit.
> Note: If you use windows the following commands should be run in git bash.
First if you want to make a change, you'll need a copy of the code, while you
can use the mirror from codeberg, it is recommended that if you're going to
make changes you fetch from Gerrit Directly, and it is *required* you setup a
git hook to attach Gerrit "change ids" to your commits:
```bash
git clone "ssh://<gerrit-username>@gerrit.miku.build:29418/rem-verse/lisa"
cd "lisa"
mkdir -p `git rev-parse --git-dir`/hooks/
curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.miku.build/tools/hooks/commit-msg
chmod +x `git rev-parse --git-dir`/hooks/commit-msg
```
From this point on you can mostly use git _as normal_. When working on a change
you can checkout your own branch, rebase it, fetch, etc. all like normal. The
only thing changes when you go to _commit_ your changes to finally push them.
Gerrit _forces_ your commits to be 'clean', and each commit is directly linked
with a change. Gerrit does have native support for 'stacked' changes where you
can commit many changes at once, rebase them all at once, etc. However, the key
working model is one commit == one change, and any updates or modifications to
that change will be an _amend_ of that commit, or a rebase of that commit.
### Example Workflow ###
As an example let's walk through a typical change that might have to go through
multiple rounds of review, and what that might look like:
1. Start a new branch off of the latest `trunk` to begin work:
- `git checkout trunk`
- `git pull`
- `git checkout -b <username>/my-cool-new-feature`
2. Make your changes to the source code as necessary.
3. When you are ready to make your changes, commit.
- `git commit`
- *note: you'll notice after if you do a `git log` there's a
"Change-Id" line that's been added by the git hook we setup
when originally cloning the repository. This is important,
and it represents the pull request or 'change' in gerrit
parlance.*
4. Push the change up for review:
- `git push origin <username>/my-cool-new-feature:refs/for/trunk`
5. A maintainer will come along, and approve for CI running, and may leave some
comments.
6. You make any changes as necessary to your source code from the review comments.
7. You update your commit:
- `git commit --amend`
- *MAKE SURE TO NOT REMOVE THE CHANGE ID LINE.*
8. If any changes have merged that now conflict with yours, you can rebase as necessary:
- `git checkout trunk`
- `git pull`
- `git checkout <username>/my-cool-new-feature`
- `git rebase trunk`
- *make any changes necessary as you `git rebase --continue`, and make sure to NOT REMOVE the change id line*.
9. Finally push again to update the change:
- `git push origin <username>/my-cool-new-feature:refs/for/trunkl`
Click the submit button as necessary, and if you ever need to re-run tests without a
change, after the change has been approved you can simply comment: `/retest` on the
change to automatically retrigger any failed tests.