Github workflow for collaboration

[gambhiro]

Treat the main branch as 'ready/working/clean' code.

The workflow in brief:

1. create a feature branch
2. make commits there
3. when you are finished with a chunk of work, rebase and merge with --no-ff back to main
4. delete the feature branch.

(This is the "Option 3 – rebase + merge –no–ff" of the OneFlow method.)

Start a new feature branch from main:

$ git checkout -b feature/my-feature main

Nothing special about the name feature/my-feature, can be more literal, e.g. gambhiro-fixes.

... do some work, make commits ...

It is not necessary to push your feature branch to github, unless for discussion or review.

When ready to integrate a clean block of work back to main:

First, pull the commits which others have added in the meantime.

$ git checkout main
$ git pull origin main

Checkout the feature branch and rebase it, which places your commits at the top of the history. (See rebase explained.)

$ git checkout feature/my-feature
$ git rebase -i main

If your changes conflict with the changes others have made, there will be a merge conflict. Resolve it with a difftool such as meld by choosing which parts to keep.

Then continue by mergin the feature branch into main.

$ git checkout main
$ git merge --no-ff feature/my-feature
$ git push origin main
$ git branch -d feature/my-feature

And you get a history as below (graphics has 'master' instead of 'main').

If you pushed your feature branch to github, delete the remote branch:

$ git push origin --delete feature/my-feature

[bdhrs]

Is there a simple way to do this VSCode? Or only by command line?

[gambhiro]

I don't use it so I wouldn't know. A quick search turned up plugins for git flow (which is a more complicated method) but the plugins are more confusing to me because I don't know what git commands their custom actions translate to.

I'd recommend doing that little dance on the command line.

[Devamitta]

Yes, it would be particularly easy during the vassa =)

[gambhiro]

Ven. @Devamitta asked a question in email which is worth pointing out:

When I am working in that branch, would I be able still to receive all latest changes committed by others while I am still working on my deva-branch?

Think of a branch not as a permanent identifier, but as an ephemeral place to hold some changes temporarily. So one is creating and merging branches as a regular thing (even with the same name, such as a develop branch).

The idea of a feature branch is to keep changes isolated (so your changes don't conflict with someone else's) but merging it back when you are ready to send those changes back to main.

At that point your history is integrated into other people's history (i.e. you are also receiving their changes).

After merging it, you delete the branch, create it again from main, and keep going.

This process limits possible merge conflicts to the time when you are merging the branch, instead of conflicting with every git push on the same branch where someone else was also changing things.

We're probably not going to be doing all that much anyway.

[Devamitta]

Ajhan,

For this reason, I moved most of the code related to mine into the dps folder. This way, we with Ven Bodhirasa can work on different files.

The only thing I failed to move is the GUI because dps_tab and dpd_tab are part of the same GUI. Despite my attempts, I encountered a continuous error: "ImportError: cannot import name 'function name' from partially initialized module 'path' (most likely due to a circular import)." As a result, I kept them together.

Would it work if I commit less frequently, only when it's necessary to share code with collaborators?

[gambhiro]

Is the GUI specifically for editing the DPS, or do you mean making a copy of it as a separate GUI? It may not be necessary to move.

If the DPS is an isolated sub-project, it could also make sense to move it into a separate repo as a python package, and import the dpd-db from there.

Circular import errors happen when A imports something from B, but B, or one of B's imports, imports something from A.

It can be resolved by identifying the module or functions, and moving them into a new module which both A and B can now import without being circular.

[Devamitta]

The GUI opens a window with multiple tabs, and editing DPS is one of them. (Now even 2) There's also a vast While loop in gui.py that I attempted to separate. However, perhaps we should keep it as is. Since the DPS tab has only recently become a part of it, substantial editing will be necessary. With minor adjustments later, we hope to be able to merge it with Ven. Bodhirasa's work.

[gambhiro]

When I opened gui.py the code linter had a lot of warnings. To Ven. Bodhirasa I recommended using both pyright and ruff, both have VS Code plugins. They cover many obvious checks.

For example below, the problem is that .get_next_focus() may return None, which will not have a .set_focus() method, and can crash with a runtime error.

This can be avoided by first checking for None, e.g.

focus = window['dps_meaning'].get_next_focus()
if focus is not None:
    focus.set_focus()

[bergentroll]

I recommended using both pyright and ruff, both have VS Code plugins. They cover many obvious checks.

Also flake8 and mypy is still good time-tested options, one for code style checking and the second for type checking. Have VSCode support too [1], [2].

[gambhiro]

As I understand them, ruff replaces flake8 but is faster with more options.

I found mypy to be too strict for me on codebases which were not written with types in mind, especially the warnings about imported libraries which don't provide type hints.