Discussion:
New Fossil user experiences
(too old to reply)
Andy Goth
2018-07-11 02:58:57 UTC
Permalink
I'm working on a project with a new Fossil user. Right now it's just
the two of us. He was able to create the Fossil repository on Chiselapp
without any fuss, but since then it's been all my work, aside from his
wiki edits. Until today. Now is the first time he tried cloning the
repository onto his computer and checking in edits. With his
permission, I'm going to share some of his experiences here.

The first thing he said was "Got fossil ui working. Added, merged and
committed website_design.md." I thought it interesting that he spoke of
merging as if it were a distinct task in the workflow for adding a file.

Then a bit later, regarding that same file: "Ah, I'm seeing this would
be better suited as an addition to the roadmap [a separate document].
I'm reading the best practice for fossil is to leave the deprecated .md
in place?" I'm not sure where he got the idea that it's best to not
delete files, but he did. Maybe I should ask.

I explained to him a bit about fossil changes, commit, rm, extras, etc.
"'fossil changes' lists all the changes that will be committed the next
time you do a 'fossil commit'. By default, 'fossil rm' doesn't delete
the file from disk, only marks it to be removed in the next commit.
It'll still stay on disk until you delete the file for real. People
don't much like this behavior, but it's what we have, and it can be
changed."

Regarding fossil changes, he said, "If I get a carriage return/new line
with no prompt, does that mean there are no changes to apply?" So there
seems to be a bit of confusion, or at least hesitancy, about fossil
changes (probably also fossil extras) printing nothing.

Then the big challenge: "I've been trying to get the file removed from
the online repo, ran fossil rm here and now am having difficulty
committing."

We went around on this for a while until I was able to correctly guess
that he had typed "fossil sync website_design.md" in order to "sync" the
file to Chiselapp. This was easily fixed with fossil remote-url.

He said, "okay, I want to remove website_design.md and sync." I
responded, "Type 'fossil rm -hard website_design.md' and 'fossil
commit'. The '-hard' will go ahead and delete the file from disk for
you. I can change the default to do that all the time if you like,
since that's what people usually expect." He said, "Yes please." From
that, I take it that the default of not deleting the file from disk is
confusing to new users. As for me, "I've gotten used to just typing
'-hard'."

I then looked at the history and found that he actually added and
deleted website_design.md twice. He explained, "Yes, I was trying to
work off of a git tutorials as I had found the Fossil resources to be a
bit more sparse. Even after removing a file you run git add to apply
those changes." Interesting.

At that point I asked his permission to share and if he had anything to
add. His advice: "Take it a bit further with the quick start tutorial.
Past the point of cloning or initing I'd like to have a step by step
through adding, commits, and how the auto feature changes the experience
from git or how it works in general."

I pointed him to the /md_rules page, and he said, "This will come in
handy, thank you." So perhaps we could do better highlighting the
resources we already have.

Lastly, a technical problem. I have a markdown document with an image
in it, but it wasn't showing up for him. The solution was to look at it
using /doc since /artifact was preventing the relative URL from
resolving to a usable resource.
--
Andy Goth | <andrew.m.goth/at/gmail/dot/com>
Warren Young
2018-07-11 21:10:37 UTC
Permalink
"Got fossil ui working. Added, merged and committed website_design.md." I thought it interesting that he spoke of merging as if it were a distinct task in the workflow for adding a file.
Did he check the file in on a branch and then merge it down to trunk?
“...I'm reading the best practice for fossil is to leave the deprecated .md in place?" I'm not sure where he got the idea that it's best to not delete files
It’s not Fossil-specific at all: once publicized, a URL should never die, else you get broken links, if only from web crawlers that saw that document once upon a time and then continue to return it in search results.

There are several embedded documentation files in both the Fossil and SQLite project repositories that are deprecated, presumably for this reason.

It’s arguable whether this rule applies to your codeveloper, because page lifetime also plays into it. It sounds like the file was only available for minutes, and then on a “young” site with very few outside people looking at it, if any at all. So, who could possibly have even known the URL was valid, much less cached it semi-permanently?
“People don't much like this behavior, but it's what we have, and it can be changed.”
Did you make it clear that “it can be changed” means your codeveloper can change it on his end, as opposed to waiting for someone to get around to changing Fossil for him?

Two weeks ago, Fossil trunk was changed so that you no longer need to reconfigure Fossil’s checkout tree to enable this:

http://fossil-scm.org/index.html/info/27e5e5ce65262f5a

That is, the mv-rm-files option is now present in all Fossil builds. It is just not enabled by default.
Regarding fossil changes, he said, "If I get a carriage return/new line with no prompt, does that mean there are no changes to apply?" So there seems to be a bit of confusion, or at least hesitancy, about fossil changes (probably also fossil extras) printing nothing.
That’s not a Fossil issue, it’s a Unix vs Windows issue: traditionally-designed Unix programs often do their work silently if no problem occurs and there is nothing to tell the user.

This design choice is part of Unix’s focus on the shell as a programming environment, rather than as a thing to type commands at interactively. DOS never developed this tradition of scripting commands and interpreting stdout and stderr, so Windows inherited that, and thus Windows programs tend to blabber.

Compare the operation of Unix cp vs DOS COPY, for example.

Fossil comes out of the Unix tradition, so Fossil only writes output when it has something important to tell you, or you asked it to tell you something.
fossil sync website_design.md
That the sync command stores the given URL blindly here seems like a UX bug to me. Just as Fossil re-prompts for a password until it gets one that works, it should not store the URL until it successfully uses the given one to sync the local repo.
This was easily fixed with fossil remote-url.
I’d have told your codeveloper to use “fossil sync URL” here instead, so he could compare and contrast the incorrect and correct forms of the command.

By giving him a different command to back out, he may now be afraid to use “fossil sync” entirely.
the default of not deleting the file from disk is confusing to new users.
Yes, well, the argument’s been had for years here. I take the recent change on Fossil trunk as a sign that *eventually* the default will change. We shall wee.
Andy Goth
2018-07-13 15:39:45 UTC
Permalink
Post by Warren Young
I thought it interesting that he spoke of merging as if it were a
distinct task in the workflow for adding a file.
Did he check the file in on a branch and then merge it down to trunk?
No he did not, but after reading my email to this list, he told me he
said merge because his git habit is to always work on a branch. I took
that as an opening to discuss the difference between git and Fossil
branches.
Post by Warren Young
"...I'm reading the best practice for fossil is to leave the
deprecated .md in place?" I'm not sure where he got the idea that
it's best to not delete files
It’s not Fossil-specific at all: once publicized, a URL should never
die, else you get broken links, if only from web crawlers that saw
that document once upon a time and then continue to return it in
search results.
Ah, that makes sense. Except, our project is private, and at the moment
the two of us are the only ones with logins. Only the front page and
the wiki are public, and I've been migrating most of our wiki stuff to
the private areas because in my opinion it gives away too much secret
sauce. Probably not worth shunning wiki history though.
Post by Warren Young
"People don't much like this behavior, but it's what we have, and it
can be changed."
Did you make it clear that "it can be changed" means your codeveloper
can change it on his end, as opposed to waiting for someone to get
around to changing Fossil for him?
Yes, I told him the command to type to change the setting. Though at
the time I was stupidly hoping that it was a versionable setting, in
which case I could change it for him. Of course it's not, and I'm not
asking for it to become one.
Post by Warren Young
Two weeks ago, Fossil trunk was changed so that you no longer need to
http://fossil-scm.org/index.html/info/27e5e5ce65262f5a
I told him the binary he downloaded from the website probably wouldn't
have the ability to change the setting on the fly and that I might have
to provide him with more current binaries. Though I'll have to leave it
to him to make his own macOS binary, since I'm only set up to build for
Linux and Windows at the moment. (He uses macOS and Windows.)
Post by Warren Young
Regarding fossil changes, he said, "If I get a carriage return/new
line with no prompt, does that mean there are no changes to apply?"
So there seems to be a bit of confusion, or at least hesitancy, about
fossil changes (probably also fossil extras) printing nothing.
traditionally-designed Unix programs often do their work silently if
no problem occurs and there is nothing to tell the user.
I am well aware. I'm just reporting new user experience. It really
does drive me nuts when programs have a special case to report nothing
since half the time I've got them talking to other programs (rather than
a human) and I need to put in a matching special case to not treat "no
changes found" as the name of a file being changed.
Post by Warren Young
fossil sync website_design.md
That the sync command stores the given URL blindly here seems like a
UX bug to me. Just as Fossil re-prompts for a password until it gets
one that works, it should not store the URL until it successfully uses
the given one to sync the local repo.
Very good point. And if we really do want to force the URL, for example
in the rare case that the system is being prepared for remote sync'ing
but the network or server isn't immediately available, that's what
"fossil remote-url" is for.
Post by Warren Young
This was easily fixed with fossil remote-url.
I’d have told your codeveloper to use “fossil sync URL” here instead,
so he could compare and contrast the incorrect and correct forms of
the command.
Hmm, right. Good point.
Post by Warren Young
By giving him a different command to back out, he may now be afraid to
use “fossil sync” entirely.
I already told him he should never need to use "fossil sync" manually.
We've not gotten to the point of using any of the commands that don't
sync on their own.

He's no dummy. He's just trying to come out of the git fog.
Post by Warren Young
the default of not deleting the file from disk is confusing to new users.
Yes, well, the argument’s been had for years here. I take the recent
change on Fossil trunk as a sign that *eventually* the default will
change. We shall wee.
Nice typo. ;^)
--
Andy Goth | <andrew.m.goth/at/gmail/dot/com>
Warren Young
2018-07-13 17:23:58 UTC
Permalink
Post by Warren Young
I thought it interesting that he spoke of merging as if it were a
distinct task in the workflow for adding a file.
Did he check the file in on a branch and then merge it down to trunk?
No he did not, but after reading my email to this list, he told me he said merge because his git habit is to always work on a branch. I took that as an opening to discuss the difference between git and Fossil branches.
In my public Fossil projects, the policy is that any checkin that is potentially destabilizing should be done on a branch, as should any coherent line of work that will require multiple checkins to complete. Trunk is ideally stable at all times, so as long as a checkin is self-contained and trunk remains as stable as before, direct checkins to trunk are fine.

The rule requiring multiple-checkin lines of work to be on a branch doesn’t apply if each step along the way is self-contained and doesn’t destabilize trunk. So for example, work on a new script that requires multiple checkins can be done directly on the trunk as long as that script isn’t called by something other developers run frequently, such as the build system.

This is an ideal not always achieved, but since there are consequences to not achieving it, over time developers on the project learn to be thoughtful about checking in directly to trunk.

As a result of this policy, a new developer’s first checkin might well be on a branch, either because they’re going off on a new development tangent that will take them multiple checkins to finish, or because they’re still feeling tentative about their work, so they want one of the old hands to okay it before merging it to trunk.
Post by Warren Young
once publicized, a URL should never die
our project is private
In that case, I think it’s perfectly fine to delete these docs unceremoniously, as needed.
Only the front page and the wiki are public, and I've been migrating most of our wiki stuff to the private areas because in my opinion it gives away too much secret sauce. Probably not worth shunning wiki history though.
Until one of the publicly-hosted “private” repository services is designed to and audited at the same level we use for VPNs, I’m unwilling to trust any of them.

If your codeveloper is remote from you, I recommend that you relieve Fossil of the burden of providing the capital-S security for your project, laying that off on SSH or some VPN technology you trust instead.

I’m not a black hat, so I haven’t tried to break Fossil’s permission system, but I only depend on it about as much as a door lock: it’s a thing to prevent civilized users from doing things we’d rather they not do. If I decide that a Fossil repository’s contents shouldn’t be visible to the public, I don’t put it on a publicly-accessible server, period.

If you want to treat Fossil as a CMS for your public web site, I’d run it as a separate instance, with only those things you’re willing to publicize going out to it.

For off-site backups of private repositories, I use the attached script. Technically it violates my rule not to put private data on publicly-accessible servers, but I trust AES, gpg, and my key to turn that repository data into a blob of useless noise to anyone without the key.

There are several things you need to adjust in the script to use it:

1. The “pass” value on line 3. I use a generated random blob, but it could be a passphrase or similar. If it’s short enough to be called a password, run it through an entropy calculator: if your password gives less than 256 bits of entropy, you’re artificially weakening the encryption.

2. The repository list used in the “for” loop.

3. The “bdir” output directory. It could be something like ~/Dropbox/Fossils, or it could be a directory sync’d elsewhere by a command that you append to the script.

I’ve come to this position not out of specific distrust over Fossil’s security design, but out of deep respect for what the ‘hats can do once they’re feeling motivated to attack something. SSH, VPNs, GPG, and AES have all been pounded on by the ‘hats sufficiently long and hard that I trust those technologies implicitly, as long as the best practices are followed.

Since Fossil hasn’t attracted that sort of attention yet, I feel that my idea of “best practice” for Fossil security is just my opinion and worth only as much as that realization implies.

While I’m pontificating on paranoia, I’ll say that a VPN is only a VPN if it is truly private. Technologies which fail to provide the “P” are not VPNs. Hence, PPTP is not a VPN, in my view:

https://en.wikipedia.org/wiki/Point-to-Point_Tunneling_Protocol#Security
I'll have to leave it to him to make his own macOS binary
Here’s the current trunk, built a couple of hours ago on a macOS 10.13.6 system:

https://drive.google.com/open?id=1Pl3XQAVtJOv-LXTlZmPyP_tkNML9YJDa

It appears to be linked to the Homebrew version of OpenSSL, so he’ll need to have that installed to run it.

I won’t be upset if you decide not to download and run that, having endured my lecture on paranoia. I tell you it’s a safe binary, but who am I to certify that?
Post by Warren Young
By giving him a different command to back out, he may now be afraid to
use “fossil sync” entirely.
I already told him he should never need to use "fossil sync" manually.
There are two fairly common cases where he may need to sync manually:

1. Fossil UI -> edit wiki.

2. Ditto, but with tickets.

On saving the ticket/wiki changes, the local Fossil instance won’t autosync to the remote instance, even if it’s available and autosync is enabled.

I also do manual syncs when taking a laptop that had autosync disabled back into the warm wifi bath after re-enabling autosync.
Post by Warren Young
We shall wee.
Nice typo. ;^)
We did, and we thank you for your concern over our urological health. :)
Andy Goth
2018-07-13 18:24:05 UTC
Permalink
Post by Warren Young
In my public Fossil projects, the policy is that any checkin that is
potentially destabilizing should be done on a branch, as should any
coherent line of work that will require multiple checkins to complete.
Trunk is ideally stable at all times, so as long as a checkin is
self-contained and trunk remains as stable as before, direct checkins
to trunk are fine.
That's a good policy, though in this situation all his check-ins have
been project planning documentation. The code is my responsibility at
this point. Also there's no worry about destabilization because we
aren't stable to begin with. Once we have a working platform, I do plan
to institute a policy like yours.
Post by Warren Young
If your codeveloper is remote from you, I recommend that you relieve
Fossil of the burden of providing the capital-S security for your
project, laying that off on SSH or some VPN technology you trust
instead.
If the guy with the money believes Chiselapp's security is good enough
for him, it's good enough for me, especially since I'd have made it
fully public if it were entirely my decision. I just didn't want to put
implementation details in a section that's expressly public.

For a different paid project much more strongly commercial in nature, I
hosted Fossil myself to avoid trusting Chiselapp or any other such
public host. 350MHz Pentium II with 256 megabytes RAM, by the way.
Post by Warren Young
For off-site backups of private repositories, I use the attached
script. Technically it violates my rule not to put private data on
publicly-accessible servers, but I trust AES, gpg, and my key to turn
that repository data into a blob of useless noise to anyone without
the key.
Thanks. I may have need of that at some point.
Post by Warren Young
I'll have to leave it to him to make his own macOS binary
Here’s the current trunk, built a couple of hours ago on a macOS
https://drive.google.com/open?id=1Pl3XQAVtJOv-LXTlZmPyP_tkNML9YJDa
It appears to be linked to the Homebrew version of OpenSSL, so he’ll
need to have that installed to run it.
Not up to me. I don't have macOS anywhere at home or at work. We used
to have some vendor-supplied Mac Minis, but I think they were running
Linux anyway.
Post by Warren Young
1. Fossil UI -> edit wiki.
2. Ditto, but with tickets.
True, though he has just used Chiselapp directly so far, and is now
focusing on checked-in documents instead. I'll have to remind him about
the doc/ckout feature so he can preview his changes.
--
Andy Goth | <andrew.m.goth/at/gmail/dot/com>
Loading...