Hey,

Since I just recently figured that stuff out, my perspective might be useful.

I do not think it is a good idea to push external VCS too much at this point. They are important to collaboration, so they should be mentioned, but they add a lot of complexity.

Taking into account the feedback from Sven, and my own ideas, here's how I would write it. I hope this helps.

1. The virtual machine��(VM) provides the environment where the Pharo system lives. It is different for each operating system and hardware architecture, and runs as a machine language executable in the operating system. It implements the details of managing memory, executing Pharo byte-code, and communicating with the world outside of the Pharo system: files, other operating system process, and the network.
2. The image��is the state of all objects in a running Pharo system: classes, method as source and byte-code, windows, VM processes. All of those are objects. The virtual machine can load image files, and save running images back to disk.
3. The sources��file is a way to save space by putting the source code of classes outside of the image. Since an image contains byte-compiled methods, it can run without its associated sources files. This file only provides information that useful to the programmer. It is generated once per major release of Pharo, and is usually stored in the same directory as the image. Several images can use the same sources file.
4. The changes��file logs all source code changes since the generation of the sources file. It lets you examine and revert source code changes. It also serves as a journal so you can recover changes you made but did not save to the disk image, by mistake or because of a crash. An image does not need its changes file to run. Each change file belong to a single image.

NOTE: Some virtual machines run in web browsers, and are Javascript programs instead of machine language. They provide the same services as other virtual machines, they just treat Javascript as the machine language and the browser as the operating system.

The image, sources and changes files are portable across operating systems, and��can be copied and run on any appropriate virtual machine. The format of the sources and changes file is defined by code stored in the image, not the VM.

A complete Pharo release contains the following files:

• An executable virtual machine, named:
• Pharo.exe for Windows;
• pharo for Linux;
• Pharo for OS X (inside a package named Pharo.app).
• An image, named after the release: Pharo4.0.image
• A sources file, named after the release: PharoV40.sources.
• A nearly empty changes file, named after the image: Pharo4.0.changes

They are starting point for a live environment that you adapt to your needs. The .image file containes the��byte-compiler of the language, the language parser, the IDE tools, many libraries and provide a virtual operating system that runs on top of a virtual machine.

As you work in Pharo, the .image and .changes files are modified, so you need to make sure that they are writable. The��.image��and��.changes��files are intimately linked and should always be kept��together, with matching filenames. Never edit them directly with a text editor, as��.images��holds your live object runtime memory, which indexes into the��.changes��files for��the source.

It is a good idea to keep a backup copy of the downloaded��.image��and��.changes��files so you can always start from a fresh image and reload your code. But to manage changes on larger projects you should also��use a version control system that will provide more control to record and communicate your changes.

The four main component files above can be placed in the same directory, although it���s also possible to put the Virtual Machine and sources file in a separate directory where��everyone has read-only access to them.

If more than one image file is present in the same directory pharo will prompt you to choose an image file you want to load.

Do whatever works best for your style of working and your operating system.