This article is an attempt to define a bazaar model workflow for accepting contributions in AsmBB project.

The main problem with this workflow is that most of the projects that use Fossil actually use the cathedral model of development. This way, the most of the developed workflows and best practices are related to the cathedral model of development.

But as long as fossil is really great tool, it deserves to be used more widely. And it actually has the features needed for the bazaar model.

The most important difference of this workflow, compared with the simple files exchange is that when merged to the repository, all the changes will be labeled with the authors name and will have the original authors comments and the normal development history. This way helping in the future development.

Notice, that the below workflow is created in accordance with my understanding of fossil. It can be edited in the future, if something works not as expected.

On the other hand, everything concerning the work on your local computer can vary in accordance with your preferences (for example, the repository location, working directories, etc.)

In the below code, all placeholders are in UPPER_CASE. Replace them with appropriate values.

1. Clone the AsmBB repository:

$ fossil clone https://asm32.info/fossil/repo/asmbb MY_FOSSIL_REPOS/asmbb.fossil

Because every fossil source repository is a single SQLite database file and because fossil does not have special working checkout directory (for example like git has), it is a good practice to keep all your cloned repositories in a special repository directory and then to open as many working directories as you need.

In the above command, MY_FOSSIL_REPOS is the path to this repository storage directory.

2. Create working directory and open the repository inside:

$ mkdir MY_WORKING_DIRS/asmbb
$ cd MY_WORKING_DIRS/asmbb
$ fossil open MY_FOSSIL_REPOS/asmbb.fossil

The above commands will open the repository and extract the latest version of the branch trunk. It is not so important, because you will need to create new branch for your changes.

3. Set the autosync setting to pullonly:

$ fossil settings autosync pullonly

This setting will prevent the automatic synchronization of fossil attempts to push your changes to the central repository, but it will still auto pull the changes and merge them if needed.

4. Now create new branch for your changes (from the branch trunk) and check-out:

$ fossil branch new MY_SHINING_FEATURE trunk
$ fossil co MY_SHINING_FEATURE

5. Now start your development. Edit the files, test, etc. On your estimation (but not too rarely) make commits of the current development state. Don't forget to write meaningful comments on your check-ins.

$ fossil commit

6. When you are ready and want your code to be merged in the project, create a bundle:

$ fossil bundle export BUNDLE_NAME.bundle --branch MY_SHINING_FEATURE

The above command will create a file named "BUNDLE_NAME.bundle". This file is a SQLite database, containing all history of the branch MY_SHINING_FEATURE as you comitted it. And it can be imported in other cloned repository or in the central repository. (the command is fossil bundle import)

7. Then send this bundle to the project maintainer by any means. You can attach it in a forum post here, or sent it to me by email (johnfound at asm32 dot info) or upload it somewhere and publish a download link.

Although the best way seems to be attaching to the forum post - this way, the changes can be discussed in one place.

The attachments limit right now is 1MB per file, but my experiments indicates that this size should be enough for pretty serious changes. It is because of the fossil very effective compression mechanism.

For example a bundle containing the whole branch i18n is something like 200kB in size.

So, after the changes are reviewed and everything is OK, they will be merged into the central repository.