I am very new to version control software and fossil. Thank you for your work and sharing it!

Please help me understand if I am doing things in a way I will be glad for later, or will hope I did differently.

I want to version my code and make it obvious on the timeline.

So far all my repositories are mono-branch. So, no obvious versioning. Just a single timeline.

But now I have a repo in which I want to introduce a big change.

I’m guessing I should, and experimented with, fossil branch new and fossil tag add.

I named the branch between quotes, so I could use spaces and included a made up version number.

I’m thinking it should have a tag of “release” or “version” or something similar.

I like the timeline showing a nice branch and dot indicating a good place to obtain code from.

But I’m not sure the best practice for creating and flagging a release. Should I put version numbers in the branch as I did and not in the tag?

I want to get off on the right foot, before I make too many changes and adopt a workflow that will cause problems.

I have some copies of older versions of the repo if I need to go back to fix my logic.

Thanks in advance.

fossil branch new

I see no compelling need for that command other than to ease the transition from other VCSes and SCMs where creating the branch ahead of need is the only option. Fossil offers the far superior option of creating a branch at the point of need, as part of the checkin of the first commit on that branch:

$ fossil ci --branch new-branch-name

That not only saves you a few steps over…

$ fossil branch new new-branch-name
$ fossil up new-branch-name
$ fossil ci

…it means you make the decision about the branch name exactly when it is needed, not some time before, when it may not even be clear yet what it should be called, much less whether it is needed or what its initial commit should contain.

I speak from experience, both past and fresh. There is in fact a recently-made branch in one of my repositories created using the ahead-of-need command, and it's simply named incorrectly. I've gone back in and fixed it with an amendment, but I maintain that if the person who created that branch had waited until the first commit to name it, it would've been named better from the start, the context needed to do so being fresh in their head.

I named the branch between quotes, so I could use spaces

I'd encourage some other convention, along the lines of program variable/function/class names: undersores, dashes, camelCase…something. When you choose spaces, you have to get it right everywhere that spaces mean something else, like command line parameter separators.

Should I put version numbers in the branch as I did and not in the tag?

There no one right answer, no "best practice". You do it how it works for you, and it may differ from one project to the next, as needs vary.

Here in the Fossil project, the version is tagged as "version-1.23" and also as "release". The first is unique, while the second is not. This relies on Fossil's ability to pick the newest version of a tag when there are multiple options, allowing you to confidently say "fossil up release", knowing that will always get you the latest release version.

What I prefer instead is to have a "release" branch, then merge the development branch into it at the release point. The advantage is that if you say "fossil up release" and then later "fossil up" after other commits have been made on the parent branch, you remain on the release branch. With the tagging scheme, the second command will get you the latest pre-release code, not likely what you were wanting, having expressed an interest in release versions in the first place.

A third alternative I've used successfully is to not have a "release" tag or branch. Instead, I use "trunk" more or less the same way as the Fossil project does, but I then have branches for each major version going back into history. I primarily develop new code on trunk, then cherry-pick it onto past major branches when necessary. Very occasionally I will be working on an older system and thus developing directly on one of these past-version branches and then end up cherry-picking the change down to trunk for inclusion in the current release instead.

Regardless, releases are tagged on each branch with a version number only. I can say things like "fossil up v3" to go back to major version 3, but I can't generically say "fossil up release". This is fine since old major version branches are likely to be quite stable. There are flurries of time when new versions are being developed on those old branches, but this is unlikely to last more than a day or so, after which point it goes back to being stable.

There are doubtless other schemes. The main thing I'd caution against is getting too clever too early. Don't make things any more complex than necessary, and add complexity only at immediate point of need. YAGNI!

Basically a branch is per definitionem different from trunk - or other branch. I'd say that a tag is the right choice here; you cannot transplant a slice of trunk a posteriori, unless the slice contains the tip thereof.

If you'd still like to have a visually outstanding, sitting-on-its-own-branch version, I guess I'd use a trick, check out the respective trunk check-in, make some minor change - be it as stupid as whitespace or as smart as a comment describing the shiny new version/release - and then commit it (fossil ci -branch) on the fittingly named new branch.

my noobiness to long established nomenclature is at the root of some of my misunderstandings

Then you should go through the glossary.

I slightly thought the tags would be shown on the timeline,

They are.

Here, for instance, is the Fossil v2.24 release commit. The tags are in the lower-right corner of that view: "trunk, release, version-2.24".¹

If you are seeing this now for the first time, it's because that URL changes the default timeline mode to "modern", which includes such things. The only mode that doesn't show that is "compact".

---

1. ^{^} And yes, "trunk" is a tag, specifically a propagating tag, which as you now know from the Branching doc to be what distinguishes a branch from a fork. Fossil is currently hard-coded to apply the propagating "trunk" tag by default to the initial commit, but it's not strictly required that it do that, or that it be called "trunk".

I slightly thought the tags would be shown on the timeline, [adding back] next to the event, when “Tags” was chosen from the pop-up menu,...

They are.

Here, for instance, is the Fossil v2.24 release commit.

Hm, what I meant was the section of the timeline I thought was devoted to Tags. Sorry for not being as clear as I should have been.¹

I’ve been using Compact View (& Any Type) on /timeline since nearly my first use of fossil ui (~ ½ year), and thus haven't seen tags since the metadata between the parentheses is hidden by default.

I’ve preferred the Compact View to Modern View, Columnar View, Verbose View, and Classic View. I respect these differences.

I think I’ll change my default view.

---

1. ^{^} Having digested more of this, I now understand showing some tag’s entire content could be excessive. In fossil’s own /ci_tags/ path I notice a commit’s comment, could be updated after the commit. Some of my commit messages are not just a sentence or two.

...So far all my repositories are mono-branch. So, no obvious versioning. Just a single timeline.

There is versioning every time you commit changes into the repo. That's what you refer to in the timeline. Each version is identified with its checkin-id, which is a SHA256 string.

So for all practical purposes you may just refer to any given version by that checkin-id, often abbreviated to first 10 chars (from left).

You may add a handy tag (or tags) to be associated with that checkin-id, so it's more meaningful, like v0.1 or whatever. Then you may refer to that checkin-id using that tag as well.

For release purposes some project do just that and release off the trunk; no additional branches needed. If your project is like that, than it can just remain "mono-branch".

Projects that support multiples releases/versions of the product at a given moment (that is back-propagating fixes or new features into already released versions) would want to branch off the trunk at the release point, and cherry-picking the updates into that branch. This way allows patch-releases for the existing versions.

Again, small projects often just push a new version and ask users to update instead of supporting patch-releases for older versions.

You may read on semantic version convention, to differentiate between major, minor, and patch versions.

Thanks for your knowledge.

You may read on semantic version convention, to differentiate between major, minor, and patch versions.

That’s what I was attempting to describe: semantic version convention.

So for all practical purposes you may just refer to any given version by that checkin-id, often abbreviated to first 10 chars (from left).

Yes that can be very helpful, but I wanted to create traditional (ahem, semantic) version numbers which most people, including developers are familiar with, and can instantly tell if there’s an increment or not and how significant it’s claimed to be. To me, check-in ids are not a practical means to ask non-technical people to track updates, I wouldn’t wish it on myself. ;-) The objective/subjective mishmash that’s semantic version control is much nicer.

For release purposes some project do just that and release off the trunk; no additional branches needed. If your project is like that, than it can just remain "mono-branch”.

Adding a tag-only did cross my mind, but I want non-tech people, and visual people like me, to see/have a spur off the main development trunk. I’m glad CSS colors the row. :-)

Regarding multiple branches
So far I am still learning how to operate fossil. Reading docs before trying. But now not a day goes by I don’t have multiple commits to my own repos. My stuff is solo for now. I think fossil has much potential, I know I’ll design repos to share. But I feel I need to learn more first.

Each version is identified with its checkin-id, which is a SHA256 string.

Maybe a typo, but really SHA3-256. I did a double-take myself when I noticed the difference. After learning a bit more, I updated my own hashing script to offer and use SHA3-256. Looking at the repo for fun, where I keep the script, I see that was before I started putting my stuff in fossil! I guess it took me another 2.5 weeks to test out, learn, and trust fossil -- based on the date of the first commit and my comments in the script.

With no disrespect to the docs, I tried the one-liner but I didn’t expect to be left on the branch. So my next test commits were on the branch and not the trunk. This threw me. But now I’ve been out on a limb (ha ha) I better understand some of the command line manipulations.

Background
In my own troubleshooting I’ve found it helpful developers have left previous release versions on their website since I could not begin to track down which specific commit caused a negative change for me. And the ratio of commits-to-a-project to releases-of-the-project is usually huge.

I downloaded all the releases I didn’t have, which were between the one I knew it worked and the current release. Then I had to build them one-by-one to figure out where the feature I relied on, broke.

At some point I hope to track (i.e. clone and then pull from) a few projects on github. Perhaps fossil’s features would have brought it to my attention faster.

For the time being I don’t intend on generating tar.gz files of my repos, but I do think it’s important to use semantic version numbering, as subjective as it is.

Besides the visual of the branch, if there’s a reason for using and maintaining the older branch, it’s an option. Now I think about it, perhaps it’s even an option to go to a specific check-in, long after the fact and create a new branch at that point, and have it appear on the timeline, say, 2 months prior. I’ve not experimented.

Update: picky edits.