Git Workflow

Explanation: Git Branching Strategy

In the developer workflow, master is referred to as the trunk. Feature work should begin from upstream/master.

Feature branches make reviews easier because each branch contains a related set of edits. Contributors should avoid merging trunk or other branches into a feature branch when possible. If trunk changes need to be incorporated, rebasing is preferred because it replays feature commits on top of the latest trunk and keeps history easier to read.

A rebase transforms a history like:

      A---B---C cool-feature
     /
D---E---F---G trunk

into:

              A'--B'--C' cool-feature
             /
D---E---F---G trunk

Merge conflicts can occur if the feature branch and trunk changed the same files. Resolve conflicts using the Git rebase documentation and related merge resolution guidance.

Reference: Git Command Reference

Clone a fork:

git clone git@github.com:your-user-name/tardis.git

Inspect branches:

git branch -a

Inspect remotes:

git remote -v
git remote -v show

Add upstream:

git remote add upstream https://github.com/tardis-sn/tardis.git

Fetch upstream:

git fetch upstream

Start a branch from trunk:

git checkout upstream/master
git checkout -b my-new-feature

Push a branch:

git push origin my-new-feature
git push --set-upstream origin my-new-feature

Check status and diff:

git status
git diff

Stage files:

git add new_file_name
git add modified_file_name

Commit:

git commit -m "A commit message"

Rebase:

git fetch upstream
git checkout cool-feature
git branch tmp cool-feature
git rebase upstream/master

Abort a rebase:

git rebase --abort

Force push a rebased branch to your fork:

git push -f origin cool-feature

Reset to a backup branch:

git reset --hard tmp

Inspect reflog:

git reflog show cool-feature

How-To Guide: Recover from Git Mistakes

If a rebase goes wrong while it is in progress:

git rebase --abort

If you notice the problem after the rebase and made a backup branch:

git reset --hard tmp

If you forgot to make a backup branch, inspect the reflog:

git reflog show cool-feature

Example reflog:

8630830 cool-feature@{0}: commit: BUG: io: close file handles immediately
278dd2a cool-feature@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
26aa21a cool-feature@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj

Reset to the point before the bad rebase:

git reset --hard cool-feature@{2}

How-To Guide: Start a Feature Branch

In the developer workflow, the TARDIS master branch is the trunk.

Do not use your local master branch for development. Consider deleting it to reduce confusion.
Fetch the latest upstream changes:
```
git fetch upstream master
```
Start from the current upstream trunk:
```
git checkout upstream/master
```
Create a new feature branch:
```
git checkout -b my-new-feature
```

Use a new branch for each separable set of changes: one task, one branch. Choose an informative name, such as bugfix-for-issue-14, refactor-density-parser, or update-regression-data-docs.

Push the branch to your fork:

git push origin my-new-feature

With Git 1.7 or newer, you can set the upstream branch:

git push --set-upstream origin my-new-feature

How-To Guide: Use the Editing Workflow

Make your changes.

Run tests to check for regressions:

pytest tardis --tardis-regression-data=/path/to/tardis-regression-data

If Sphinx is installed, check the documentation build:
```
cd docs
make html
```
The build should succeed and should not report warnings.
Check changed files:
```
git status
```
Inspect the actual changes:
```
git diff
```
Add new files:
```
git add new_file_name
```
Add modified files you want to commit:
```
git add modified_file_name
```
Check what will be committed:
```
git status
```
Commit:
```
git commit -m "A commit message"
```
Push to your fork:
```
git push
```

For a small parser change, a typical local loop might be:

ruff check tardis/io/model/parse_density_configuration.py
pytest tardis/io/model/readers/tests
git diff
git add tardis/io/model/parse_density_configuration.py
git commit -m "Improve density parser validation"
git push