diachron/docs/new-project.md

If any of the steps here don't work or are unclear in any way, it is probably a bug and we want to fix it!

how to create a new diachron project

1. Create an empty directory for your project. This directory can be inside of a git repository but it doesn't have to be.

2. Download the sync program and put it in the empty directory created in the previous step. There is a sync program for every version of diachron. You'll usually want to use the most recent stable version. [FIXME: explain why you'd want to use something else.] And you'll want the version for the operating system and hardware you're using.

3. Run the setup program. This program is [FIXME: will be] written in go, so as long as you have downloaded the right file, it ought to work.

   This will create several files and directories. It will also download a number of binaries and put them in different places in some of the directories that are created.

4. At this point, you should have a usable, if not very useful, diachron application. To see what it does, run the program develop run; it will run a simple web application on localhost:3000. To make changes, have a look at the files src/app.ts and src/routes.ts.

where do we go from here?

Now that we have a very simple project, we need to attend to a few other important matters.

version control

(These instructions assume you're using git. If you're using a different version control system then you will need to make allowances. In particular, you should convert the .gitignore file to whatever your version control system uses.)

You should add the whole directory to git and commit it. There will be two .gitignore files, one in the root, and one in the framework/ directory.

The root .gitignore created for you will be a good starting point, but you can make changes to it as you see fit. However, you should not ever modify framework/.gitignore. More on this in the next section.

working with diachron

There are four commands to know about:

• sync is used to install all dependencies, including the ones you specify as well as the ones that diachron provides
• develop is used to run "development-related" tasks. Run develop help to get an overview of what it can do.
• operate is used to run "operations-related" tasks. Run operate help to get an overview of what it can do.
• cmd runs diachron-managed commands, such as pnpm. When working on a diachron project, you should always use these diachron-managed commands instead of whatever else you may have available.

what files belong to your project, what files belong to the framework

In a new diachron project, there are some files and directories that are "owned" by the framework and others that are "owned" by the programmer.

In particular, you own everything in the directory src/. You own README.md and package.json and pnpm-lock.yaml. You own any other files our directories you create.

Everything else belongs to the framework and you are not expected to change it except when upgrading.

This is just an overview. It is exhaustively documented in ownership.md.

updates

when the docs sound a bit authoritarian...

Finally, remember that diachron's license allows you to do whatever you like with it, with very few limitations. This includes making changes to files about which, in the documentation, we say "you must not change" or "you are not expected to change."