Michael Wolf
02edf259f0
Update paths in .gitignore, cmd, develop, mgmt, sync.sh, check.sh, fixup.sh, CLAUDE.md, docs/new-project.md, and backend/*.sh scripts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
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 `diachron/` 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
|
|
`diachron/.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."
|