Version 3 of How to chisel at chiselapp.com

Updated 2019-09-03 17:33:59 by aplsimple

The excellent Fossil SCM is so distinguished against the general background (most often for the better) that it is incomprehensible why this system is still underestimated in the IT community.

In question is not the quality of Fossil - it is the highest - but the ways of presenting it. And it's here the issues come.

The issue #0.

The software behemoths can only support those VCS that can satisfy their behemothic appetites. As a result, those VCS are delivered to every home as “a must”. Though you need to be behemoth to use those VCS in full.

So, it's a real issue for those tended to be behemothic.

If you are not a behemoth and have no desire to be of this type, you can easily do without those fat meals served for begemoths. It means less dependence, less 'learning curve', less headache. It means more mobility, more time, more health. It means you can do it with Fossil SCM.

So, it's a zero value issue for those tended to be non-behemothic.

The issue #1.

The originality of Fossil necessarily leads to the original terms and approaches, which is reflected in the documentation. Not to mention the fact that this documentation leaves much to be desired, because of:

  • a lot of duplicates at the cluttered (permuted) Fossil Docs Index that was obviously designed to make it easy, but resulted in making it hard
  • the diversity of terminology that is often duplicated as well
  • scarce, if any, manuals about samples of workflow with Fossil
  • no comprehensive all-inclusive guide in the public domain

The issue #2.

Many Fossil fans are looking for a place to apply their fossil skills and often find it at chiselapp.com - a hosting service that is good in almost all respects - where, however, you don't find a word about “how to chisel at chiselapp.com ”.

Result: at chiselapp.com there are a lot of started and abandoned projects (named test*), as well as a bunch of quite good, but not quite presentable projects. As a rule, projects lack a home nor a documentation nor a download page. Illustrative stuff (pictures, videos) is missing or scarce.

There is nothing to say about Public Repositories. No sectioning, no structure, no filter by author. Although there is sorting by author but the project names go first at that. You must remember an exact name of author or resort to Ctrl+F. There are other shoals at chiselapp.com that you need at least to know about.

These were the reasons of this document.



Contents

Step by step, from registration to some customization, this document will discuss the creation of a site at chiselapp.com.

0. Registration

1. Creating a repository

2. Dashboard

3. Initial configuration

4. Home page

5. Contents of a repository

6. New skin

7. Cloning a repository

8. Pushing to chiselapp.com

9. Documentation page

10. Pictures and videos

11. Unversioned files and Download page

12. Customization

12.1 Changing permissions

12.2 Changing a skin




0. Registration

At chiselapp.com you register as follows:

  • Create Account - create your account and register.

or

  • Log in - register under your account.

I would recommend to open a separate tab of browser at registering. You have no one-click way to return to chiselapp.com from your repository.

Also, sometimes you would have to repeate Log in. It's chiselapp.com, no toys.

To work with two repositories, you can try to log-in twice in two different browser windows. For example, you can run chromium and try “Open link in incognito window” of popup menu.




1. Creating a repository

Let's say we are logged in with aplsimple account to create HOWTO_chisel repository.

After Log in, click on Create Repository to create a new repository.

You get:

Enter:

Repository name - repository name, HOWTO_chisel.

Repository password - password to access the repository: although optional, it is better to enter your own.

Make this repository private - I highly recommend enabling this option, because the site is not yet ready for publication. A private repository can be made public at any time. After all, our blunders will be visible only to us, and the public can wait.

Override project code - leave this field blank, everything works without it.

Use SHA3 for initial commit - you can enable it if the fossil version (by fossil version command) is newer or equal to 2.0; it's for more protection against hacking.

Let's click on Create repository and get the repository with the address:

  • http(s)://chiselapp.com/user/aplsimple/repository/HOWTO_chisel

which means that our HOWTO_chisel repository will be available through one of the addresses:

Click Return to dashboard. It's your own Chisel headquarters.




2. Dashboard

See the HOWTO_chisel line in Dashboard:

where you have the options:

  • HOWTO_chisel - to enter the repository

  • Edit - to publish the site and to set a new password for administrative access; useful if you did not set a password for the repository (then fossil will create its own) or just forgot the password to access the site.

It is important to note that the user password and the password for administrative access to the site are different ones. I always set a hard password for registering on Chisel, the same password for accessing public repositories and an easy password equal to the first letter of a hard one - Chisel will not allow a blank password - for accessing private repositories.

  • Remove - to remove the repository

  • How to Clone - for copy-paste of the cloning command

For now, click on HOWTO_chisel to enter the repository .




3. Initial configuration

Having entered our repository, we are looking for the Admin tab. If it is not visible, then we need to log in the repository.

Click Login and enter your username (User ID) and password for the site. If you can’t log in, you need to return to Dashboard and change the password for accessing the repository, through Edit.

It happens that when switching from one repository to another it is not possible to log in - then you need to re-login at chiselapp.com, i.e. log out and log back in. This is a glitch of chiselapp.com.

When we first enter the repository, Fossil offers to set the initial configuration by clicking on setup/config - this is what we will do:

After clicking on setup/config, you have the following options:

  • Project Name - the name of the project (HOWTO_chisel).

  • Project Description - a brief description of the project.

  • Tarball and ZIP-archive Prefix - a prefix for zip/tarball files; if left blank, HOWTO_chisel (project name) is used.

  • Download Tag - leave trunk unchanged for now (the setting will come in handy in the future when stable releases would be downloaded).

  • Enable WYSIWYG Wiki Editing - you may leave this option blank to edit markdown without fuss with html.

  • Index Page - it is better to leave this option unchanged as home; generally, you can also specify /doc/tip/index.wiki or /doc/tip/index.md, as Fossil points out; but this will mean that the home page will coincide with the documentation page, which is not good, as home is home and the docs are the docs.

  • The following settings are important:

    • Documentation Index - link to the Documentation page
    • Download - link to the Download page
    • License - link to the License page
    • Contact - link to the Contact page

To publish or not your contacts is your own decision. The contacts can be in some README as well.

But Documentation Index, Download and License must be filled. Without docs and downloads, no one needs your software. And without a license, you lose potential users - those who have heard/faced enough of the EULA stories.

I fill in the links like this:

The /download link at chiselapp.com will display the standard download and cloning page. For simple projects like HOWTO_chisel, it makes no sense to invent anything else. But if you want, you can specify /uv/download.html and get your own Download page at chiselapp.com.

The Documentation link uses a Fossil feature called embedded documentation. More about this below.

The License link may be external to the project, as in this case. Or it can be set as /doc/DOC/doc/LICENSE.md - i.e. as part of the same embedded documentation.

At last, a License link may look like this:

or like this:

  • /artifact/b4d7662bb6b0b804

This is a link to a specific version of LICENSE.txt from your project. It's easy to get it from the Files tab: right-click on Files/LICENSE.txt and select Copy link address. If LICENSE.txt is updated, you will need to update this link using Admin / Configuration.

Done with settings.

Ignore the Use HTML as wiki markup language.

Save the changes by clicking on Apply Changes.




4. Home page

It's time to think about the look of our site at chiselapp.com.

Let's log in our HOWTO_chisel repository to get administrator rights.

Then, open the Wiki tab and click on HOWTO_chisel project home page:

In the upper panel, select Edit to enter the contents of the start page.

Fossil will stubbornly offer its own Fossil Wiki markup format. It is simple and convenient, but still it’s better to choose the standard Markdown from the Markup style drop-down list.

Markup rules are available right on the Wiki tab (Formatting rules for Fossil Wiki and for Markdown Wiki).

Enter your page. You can use the preview ( Preview Your Changes ).

When the page is ready, click on Apply These Changes. Check how it works using the Home tab. We repeat all over again if there are problems.

There are tons of great programs that you can use to create and preview markdown documents. For example, ghostwriter. But the final version must still be checked at chiselapp.com.




5. Contents of a repository

Now let's look inside our repository.

Click on the Timeline tab. You will see something like:

1 check-in
2019-09-01
     09:59  [9cf295d8d7] Leaf: initial empty check-in (user: aplsimple tags: trunk)

The tags: trunk is important - it sets the name of the main branch. This is the main content of this initial commit.

There may be confusion in terms. There are synonyms for some terms and different meanings (by context) for others.

The tip means the last commit made, while the trunk means not the commit, but the name of the main branch starting from the first commit created by fossil init. As a rule (but not always), tip is on trunk and as such in commands they mean the same. Hence the confusion. If the last commit is not made on the main branch, tip and trunk refer to different commits.

There are terms that are not used in commands, but are often used in the documentation:

  • check-in , checkin, version - a commit
  • check-out, checkout - a commit that determines the state of the working directory
  • leaf - a last commit of branch; if a branch is specified in the fossil command instead of a commit, it means leaf of the branch

Special commit names:

  • current - current check-out or leaf of the current branch (in update, checkout commands )
  • next - next commit (child of the current)
  • prev, previous - previous commit (parent of the current)

When we left the trunk value unchanged in Download Tag setting, we indicated to Fossil that zip/tarball will be downloaded from the top (leaf) of this main branch.

If the main branch is under development and you want to publish the previous stable version, you can specify the tag of this version in the Download Tag setting (for example, v1.0).

The repository having been started, now it remains to clone it. Do not waste time looking for the cloning command in the default skin. Of course, you will find it - either in the Dashboard or in Admin / Configuration, but you must be an administrator to do this. Users will not see the Download page in the default skin. Another shoals of chiselapp.com.

So, we should set up a site skin where the Download page (and the cloning command) is easily accessible.




6. New skin

We select the Admin tab, then find and choose Skins.

In the Skins, we skip all initial words and go to the end of page, where we click on Skin Admin:

In the open list of skins, select to install the first one, i.e. Default Install.

Now the Download page is easily accessible from the ☰ (hamburger button):




7. Cloning a repository

Let's click on the ☰ hamburger button, then find and click Download in the Home Page list . The Download page will open, where we copy our cloning command:

fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel  clone.fossil

Instead of clone.fossil you can set your path to a future repository file. I prefer to store local Fossil repositories in the ~/FOSSIL directory, while the repository name is the same as the project name, i.e. my cloning command looks like this:

fossil clone https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil

But before any actions with repositories on the local machine, you should take care of the very important option of Fossil.

This is autosync, meaning automatic synchronization with the remote repository when committing. By default, it is turned on, which means that our commits will be automatically pushed to our chiselapp.com repository and other commits will be pulled. It only works great when we're always online.

If we are only spontaneously [sporadically?] connected to the Internet, then we should switch the auto-synchronization off. Also, the auto-synchronization may not be liked by those who do not want all blunders to be visible on the network.

We disable the auto-synchronization with the command:

fossil settings --global autosync 0

Then we execute the cloning command:

fossil  clone  https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel ~/FOSSIL/HOWTO_chisel.fossil

getting the response from fossil:

admin-user: apl (password is "123456")

where the password for administrative access to the repository is indicated. We must replace it with the command:

fossil user password apl -R ~/FOSSIL/HOWTO_chisel.fossil

You should enter the same repository access password that you set on chiselapp.com. If the password changes in the future, you will simply repeat this command.

So, the repository has been cloned. Now we go to the source directory of HOWTO_chisel. Suppose we have already some files made in this directory, then our actions will be as follows:

cd ~/projects/HOWTO_chisel
fossil open ~/FOSSIL/HOWTO_chisel.fossil
fossil addremove

Thus, in the project directory ~/projects/HOWTO_chisel, we initialized the fossil workflow with our local repository ~/FOSSIL/HOWTO_chisel.fossil.




8. Pushing to chiselapp.com

Having worked a bit on our project, having accumulated a bunch of small commits in it, we decide to upload our stuff to chiselapp.com.

If the described above fossil settings autosync is 1 (i.e. we always synchronize with the remote repository), then we have nothing to worry about. Our commits are already at chiselapp.com, we just go to Chisel and look at results.

However, if fossil settings autosync returns 0 (auto-synchronization is disabled), then periodically after committing it is necessary to download/upload commits from/to chiselapp.com, i.e. operate in an ordinary cycle: pull / update / merge / commit / push / ..local changes.

For example, the push command looks like this:

cd ~/projects/PROJECT
fossil push https://USER:[email protected]/user/USER/repository/PROJECT

where USER and PASS should be replaced with your username and password.




9. Documentation page

If the documentation page is a simple README.md, we can easily create Documentation page.

We enter Admin / Configuration and fill in Documentation option like this:

/doc/trunk/README.md

This means that README.md of the root project directory would be taken from the main branch of the repository and displayed in the Documentation page. The fossil feature called embedded documentation come in handy here.

So when we click the ☰ tab and then click on Documentation, we get our README.md converted to html.

But what if documentation should be maintained this way:

  • the documentation sources are not in zip/tarball, though are in the repository (with all their history)
  • only the generated documentation is in zip/tarball
  • the documentation is developed on a separate branch
  • the generated documentation is viewed with ☰ / Documentation

Answer:

The initial commit's artifact of our repository is [9cf295d8d7]. We will branch from it to the new DOC branch and check-out it:

fossil branch new DOC 9cf295d8d7
fossil co DOC

Then we create a bunch of source documentation files.

Usually, one makes a separate embedded subdirectory in the project root:

embedded/www
embedded/man
embedded/man/files
embedded/man/...

Then one runs a kind of documentation generator that compiles embedded/man sources to embedded/www html pages .

We will also create the sources and generate documentation, then we will commit and return to the main branch. At the same time, we will sort the source and generated documentation files into different branches - DOC and trunk.

We will continue to operate on the main branch and commit - this is necessary so that our main trunk branch comes forward in the timeline. If it is up to you to push right away, let's make an empty commit.

Details see here:

After pushing the commits to chiselapp.com, make a change in the settings of Admin/Configuration:

  • Documentation Index - /doc/trunk/embedded/www/index.html

or

  • Documentation Index - /doc/trunk/embedded/www/toc.html

The embedded documentation is good primarily for debugging in place before committing the result.

When we run fossil ui on the local machine and look at our documentation at:

http://localhost:8080/doc/DOC/embedded/www/toc.html

we will not see any changes in it until we commit, but committing what we have not seen is ridiculous. And here Fossil comes to the rescue: it is enough to replace the DOC (or standard trunk, if our docks are on the main branch) with ckout, i.e.

http://localhost:8080/doc/ckout/embedded/www/toc.html

and we will see the current uncommitted changes immediately (or after the generation of html).

This is how embedded documentation works.




10. Pictures and videos

Adding a picture to the start page or the documentation page is as easy as adding a regular html page, because markdown files allow you to use most tags on static pages, in particular, the <img> tag.

Therefore, if index.md refers to certain image files, it is enough to copy all the images into a subdirectory under index.md (for example, files) and make all image links relative, for example:

<img src=“files/colorchooser1t.png” alt=“Tcl/Tk color picker changed” />

The example of pave was made this way.

The home page is a bit more complicated, because it is created using regular chiselapp.com tools. If you need to include a picture in the home page, then where to find its address? Since the repository does not store files, but file artifacts, the start page should also link to image artifacts. For example:

<img src=“https://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/raw/bb55ed2b9ca8d40f?m=image/png” />

where bb55ed2b9ca8d40f - is the image artifact ID seen on the Files tab.

To find out the artifact of an image, you need to go to Files tab, find the image you need, click on it and go to the artifact page, then copy the artifact ID (for SHA3 it will be a rather long ID).

The same applies to other media resources stored in the repository.

But there is a preferred way to do this, when all binary resources are stored as one (unhistorical) version in the repository and the links to them look, for example, like this:

<img src=“http://chiselapp.com/user/aplsimple/repository/HOWTO_chisel/uv/picture.png” />

This method of storing data in the repository is discussed below.




11. Unversioned files and Download page

An extremely useful feature of Fossil is storing files that have no history in the repository.

This thing is designed for creating download pages and, in general, for storing binary files. In the repository, the previous versions of binaries are most often not necessary. Moreover, they fatten the repository.

Once I tried to do something similar in Mercurial , as far as Mercurial allowed to do this. Then bitbucket.org 'sunsetted' all the Mercurial people. And then Fossil came to the rescue, and the problem was solved without crutches, elegantly and beautifully.

For full information, see Unversioned Files .

Unversioned files' best location is a directory excluded by ignore-glob:

fossil settings ignore-glob .*,*~,*.swp,*.tmp,*.BIN,*.log

Due to this, subdirectories like .BIN are excluded from the repository. They are not visible to all fossil commands, except for fossil uv.

Having our binaries in the .BIN subdirectory, we execute the command uv add:

cd .BIN
fossil uv add *

The trick is that fossil uv add will ignore the ignore-glob setting and mark all .BIN/* as unversioned files that will be updated on chiselapp.com with the command:

fossil uv sync

These files will be available on all pages of the site using the links like:

http://chiselapp.com/user/USER/repository/PROJECT/uv/FILENAME

For example:

http://chiselapp.com/user/aplsimple/repository/pave/uv/pave.zip
http://chiselapp.com/user/aplsimple/repository/pave/uv/test2pave.mp4

The same links are available in Documentation page(s).

Also, in the .BIN directory, you can create an “unofficial” download page.

If it is download.html, then the “unofficial” download page can be set in Admin / Configuration this way:

  • Download - /uv/download.html

Just don't forget the clone command in your download page.




12. Customization


12.1 Changing permissions

User anonymous has the right to modify the Wiki. It seems to be a good feature, but the problem is that anonymous can go this way:

… to calmly write at the end of the Home page what he/she can only contrive. Another shouls of chiselapp.com.

In no way this should be allowed. Therefore, you must change the rights of anonymous.

We go to Admin / Users, select anonymous and cancel the Append Wiki right. After that, click on Apply changes:


12.2 Changing a skin

We can slightly change the standard skin.

Our task:

  • Remove Timeline and Branches from the tab list.

  • Add Docs and Download.

To do this, enter Admin / Skins.

We need to make changes to the settings:

  • CSS
  • Header
  • Footer
  • Details
  • Javascript

It is important to remember that these settings may not match the Default skin, even if you select Default (built-in) in the Initialize skin draft1 using. There is some kind of glitch with this.

The proper settings can be taken from the Fossil website:

https://fossil-scm.org/home/dir?ci=tip

There you need to enter skins/default subdirectory, from where the contents of the files:

  • css.txt
  • header.txt
  • footer.txt
  • details.txt
  • js.txt

should be transferred to the mentioned settings, according to the names.

While making changes to these settings, you should pay attention that the Edit SETTING for Draft1 form will open in a separate browser tab. After confirming the changes with the Apply button, you should close the tab to return to the Skins window.

In Header, changes are needed in two places:

1)

menulink $index_page Home {}
if {[anycap jor]} {
    menulink /timeline Timeline {}
}

should be changed so:

menulink $index_page Home {}
menulink /doc/DOC/doc/index.md Docs {}
menulink /download Download {}
if {[anycap s]} {
    # jor
    menulink /timeline Timeline {}
}

2)

if {[hascap o]} {
    menulink  /brlist Branches desktoponly

should be changed so:

if {[hascap s]} {
    # o
    menulink  /brlist Branches desktoponly

In short, the Docs and Download items have been added, and the access to Timeline and Branches has been changed so that these tabs are visible only to the administrator (they can still be accessed through the Hamburg button ☰, but not through the tab bar).

After these changes made, turn on the options:

  • Skin draft1 has been tested and found ready for production.
  • The current skin should be overwritten with draft1.

and click on Publish Draft1.

Now users (and you when being not an administrator) will see only the necessary:

or:

For more on skins, see Skinning the Fossil Web Interface.


to be continued