Anvil's master branch [continued]

stefano.menci · April 13, 2022, 3:34am

Continuing the discussion from [Beta] How do I depend from the development version of an app?:

Thank you.

I did a quick test and I got it to work quickly.

Mmmh… should I go ahead with the little rant about the master branch?
Why not? Here it is

As I said, I did a quick test and this is what I found out:

The default branch is master and the default environment is Published.
I created a new app and there was the master branch only.
I clicked on Publish and it created the Published environment linked to the master branch.
The master branch seems to be the production branch by design.
I clicked the Unpublish 'master' branch button, then I created the dev1 and dev2 branches. At this point:
- Checking out master shows the Publish 'master' branch button
- Checking out dev1 shows the Merge changes into master button
- Checking out dev2 shows the Merge changes into master button
The master branch seems to be the development branch by design.
I created the 4th branch published, then I created another app and used the first app as dependency.
- The dependency version Published uses the published branch
- The dependency version Development uses the development branch

The two behaviors 2. and 3. seem to be contradicting each other.

I have already created a feature request about killing the master branch a few months ago. After a few months I got used to dealing with it and paying close attention to avoid breaking a production app, however not one day has passed without inadvertently editing the master branch of a production app for at least a few seconds, and in a few cases for long enough to hear from a few users. I still very strongly believe the master branch does not belong in Anvil as is. My hopes to see my FR addressed are low, but my opinion doesn’t change:

I do have one request about the dependency management, but it is not about branches and environment.

I have not created any feature request about the relation between branches, environments and dependencies, because there are many posts out there and many hints that something is being developed (with a quick search I found one and two).

I am confident that whatever improvement will appear, it will be less confusing.

I’ll wait and see.

(I know, it sounds like a rant, but I am trying to be constructive)

stucork · April 13, 2022, 4:00am

There are many ways to use a git work flow.

It may not help but here’s the way I think about it - at least in anvil.
I typically consider master to be the development branch and what will become the production app.

I would probably stick with having a published branch (linked to a published environment) and whenever I wanted to move the the published branch to a particular commit I would:

Checkout 'published' branch
Find the commit I wanted to put into production.
right click and choose Reset 'published' branch to here

This way the published branch just points to a particular place in the version history.
I never edit the published branch directly, I just move where it points to.

This is basically how anvil_extras treats its Published and Development versions.

stefano.menci · April 13, 2022, 4:37am

Obviously this says it all:

Said that, on one hand I do like how easy it is to reset a branch to any commit. If the branch is linked to an environment, you end up publishing whatever version you want by simply resetting a branch. I do it in some simple apps.

On the other hand, more complex apps like the one I’m working on don’t have a straight line of commits. Right now I have the dev branch with the email service in test mode, with some global variables that enable more logging than in the production app and other little differences. Sometimes, while I work on a feature that will take me a few days, they ask me for a simpler and more urgent feature, so I create a second development branch. At this point I can’t reset, the production branch to one or the other development branches, I do need to merge them.

Merging instead of resetting has also another little advantage: I rarely pay attention to what’s automatically committed while debugging. Sometimes I check out an older branch, or I go back and forth between PyCharm and the IDE, so there are many commits with automatic messages caused by the continuous push-pull. When I’m ready to commit, I merge to the published branch with a meaningful message. The result is that most commits on the development branches have automatic comments and all the commits in the production branch have meaningful messages.

I do use the reset to revert the production branch to its previous commit when I inadvertently edit it.

Which happens way too often.

I like the old editor’s behavior: you can only edit the development branch. You can move the published branch back and forth (if I remember it was just right click - publish), but you can’t edit it. Simple, intuitive and safe.

I think the old behavior is ideal for beginners and also for most small apps for advanced users. Every app should be created with two branches development and production linked to two environments Development and Production. The production branch should be read-only.

Then, if you know what you are doing, you can edit the branches and environment settings and make whatever branch you want read-only or read-and-write. You can even create a branch and call it master!

stucork · April 13, 2022, 4:51am

I think that workflow still fits.

In the more complex scenario I would create various feature branches. Merge these into master as and when they’re ready. Then reset the published branch to a commit on the master branch as described above.

So I’d still use merging (liberally), I would just never merge into the published branch directly.

Again this is essentially how anvil_extras does features. We always merge feature branches into master, then when they’re ready for the published branch we reset the published branch.

I agree that the word master is confusing. In the wider world of git the default branch can be named whatever you like. More recently the trend is to call it main.

Rename master branch to main

Noted on the issue of inadvertently editing the master branch. I’ll add that to our list of things to improve.

duncan_richards12 · April 13, 2022, 4:51am

Ever since I started using a Dev branch outside of the master, I have been having the same issue. Only reason I’m not having the issue with production is the app I’m using this with isn’t published yet.

stefano.menci · April 13, 2022, 5:22am

Ok, so you are suggesting to work with 3 (or more) branches:

dev (can be more than one) to develop and debug
master to merge all the dev branches into
published to link the Published environment to whatever commit you want to pick, typically will be the same as master.

What are the advantages of adding the middleman master?

If we are talking about the published branch being read-and-write, this would only kick the can a little farther. Sooner or later I will inadvertently edit the app while published is checked out and the telephone will start ringing.

I’m not familiar with Guthub workflows, but I have the feeling that this works there because the master branch is (I think) read-only and you may want to publish several versions of a project, the latest as Published and other versions 1.0, 2.0, etc.

I have done only a few contributions to a few Github projects, and I’ve always been forced to create my own branch.

Anvil is not Github. Most apps (all of mine), unlike Anvil Extras, have only one published version. I don’t see the point of having both master and published.

But I would like for Anvil to force me to create (or checkout) a branch before editing.

stucork · April 13, 2022, 6:22am

I see master as what will become the production app, rather than the middle man.

The advantage for me is that I am treating the production app as being at a fixed stable commit.
That way I keep the production app readonly.
I’m using "production app" interchangeably with the "Published" environment associated with a published branch.

It might even be better to have a workflow where "Published" environment(s) aren’t associated with a particular branch at all.
Instead creating a workflow where "Published" environment(s) only ever point to specific commits.

In the Publish modal you can associate an environment with a branch, but also a commit:

The Production environment in this scenario is now associated with a specific commit. Since it’s no longer tied to a branch I’d have to try really hard to break production code

But again - this is just my take on it.

jshaffstall · April 13, 2022, 12:12pm

I use master as my testing branch, with an environment pointing to it I can give to external testers. It’s my last chance to find issues with what I’m planning on putting into production.

owen.campbell · April 13, 2022, 12:42pm

On projects where I’m collaborating with other developers, the master branch is where we merge changes that have successfully passed code review. Sometimes, that’s also the production version of the app, sometimes there’s a separate ‘release’ mechanism.

However, in all cases, nobody ever works directly on master. It’s guaranteed to include only code that has been reviewed.

stefano.menci · April 13, 2022, 2:04pm

It’s nice that you are allowed to do that, but I like to have the published app tracking a branch. That’s how the classic editor works, it’s easy, intuitive and safe.

I may need to use a commit instead of a branch as a workaround to the regression that allows me to edit the published branch, but I would rather have the regression fixed

I use testing as my testing branch

This seems to be the only use case where a branch called master (or main) makes sense. This is also an use case that requires some setup and knowledge of git and is not for beginners, so it shouldn’t be the out-of-the-box setup for a new app.

It was guaranteed in the classic editor with the old published branch, it is not the guaranteed with the beta editor. Not only it is possible to edit master, but Anvil keeps checking it out every time you merge from another branch and sets you up for failure.

There are obviously many different use cases, each with its own workflow, but it’s safe to say that there are two main workflows with Anvil:

Apps designed to be used as web apps
Apps designed to be used as dependencies

In both cases you want to be able to set one (or more) specific version for production while being able to safely edit the app (with one or more developers).

The classic editor does that beautifully with one version and one developer. It’s rigid, but it works out-of-the-box and it’s safe: you edit at the head of the repository and you publish a read-only branch called published. It’s easy, intuitive, safe and out-of-the-box.

The beta editor got rid of published but still requires published for the management of the dependencies, where master is the editing branch. So, if you work on a dependency app, this is neither intuitive nor out-of-the-box.

But it also tells you that master is not the editing branch, because it has buttons to merge to master.

But it also tells you that you do need to edit master because after every merge master is checked out and your first keystroke will edit it. So, if you work on a web app, this also is neither intuitive nor out-of-the-box.

I would go back to the origins and keep what was good on the classic editor and add to it. I wouldn’t try to fix things that were not broken.

A new app in the new editor should come with:

One read-only published branch linked to one Published environment
One read-and-write development branch linked to one Development environment
A Merge to published button to merge the changes on development into published

At this point you get all the features of the classic editor, it works the same way for dependencies and for web apps, it’s safe, it’s intuitive, it’s out-of-the-box, nothing is broken.

Then you can start playing with the app settings and create more branches and change their settings:

If you like to do hot fixes, make the published branch read-and-write
If you want @owen.campbell’s multi user environment, create a master (or main) branch
If you want @jshaffstall’s test environment, create a test branch with its own environment
If you have multiple production versions, you can create published-client1, published-client2, etc., each with its own environment
If you have more than one read-only branches, then there should be more more than one Merge to xxx buttons
You should be able to merge to any branch, even to read-and-write ones, using the context menu

The summary is that:

By default an app should have two branches, a read-and-write development and a read-only published
If you want anything more than that, you should be able to do it
Today the beta editor seems to be trying to give you more than that by starting with an undeletable branch called a mysterious master
This default setup doesn’t work for both dependency projects and web app projects and it’s unsafe

duncan_richards12 · April 13, 2022, 11:02pm

I would agree with that version control structure, would make things a lot safer and less prone to me forgetting to change the branch I’m working on!