From 666f1447f40a5b2901655f9d3ddd4e78eb4fe841 Mon Sep 17 00:00:00 2001 From: Michael Wolf Date: Mon, 17 Nov 2025 19:53:57 -0600 Subject: [PATCH] Add first cut at docs to create a new project --- docs/new-project.md | 84 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/new-project.md diff --git a/docs/new-project.md b/docs/new-project.md new file mode 100644 index 0000000..ff10bf4 --- /dev/null +++ b/docs/new-project.md @@ -0,0 +1,84 @@ +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](https://go.dev), 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](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."