Improve documentation on how to setup a dev environment #749
Conversation
|
@jackdbd Thanks for your issue and PRs! Will review them in detail over the next few days but from a quick skim, while there are a few things I’d like to tweak, broadly support the suggestions. Also very excited to see the LinkedIn syndicator plugin! |
| ```yml | ||
| version: '3.9' | ||
| services: | ||
| mongo: | ||
| container_name: mongo | ||
| environment: | ||
| - MONGO_INITDB_ROOT_USERNAME | ||
| - MONGO_INITDB_ROOT_PASSWORD | ||
| image: mongo:7.0.11 | ||
| network_mode: bridge | ||
| ports: | ||
| - '27018:27017' | ||
| restart: always | ||
| volumes: | ||
| - mongo-data:/data/db | ||
| volumes: | ||
| mongo-data: | ||
| external: true | ||
| ``` |
There was a problem hiding this comment.
If we include add a docker-compose.yml file in the project repo, this shouldn’t be needed. Perhaps we can link to the file in the repo instead (which would save having to make any changes later in 2 different places).
|
|
||
| Indiekit performs CRUD operations on files. These files needs to be stored in a so-called content store. Different content stores require different configurations and credentials. | ||
|
|
||
| ### GitHub content store |
There was a problem hiding this comment.
Question: do you think we should recommend testing against a GitHub repo (which is likely the most common usage), or using the file system content store plugin, which requires less configuration and can be quicker to see how files are getting generated?
There was a problem hiding this comment.
Maybe I would rephrase the paragraph like this:
Indiekit performs CRUD operations on some kind of persistence storage: a filesystem, a git repository, or an object storage like AWS S3. The so-called Indiekit content stores provide an implementation of these CRUD operations.
Different content stores require different configurations and credentials.
As for testing, I would consider both the filesystem and GitHub as external services to Indiekit, so those tests would be integration tests. I wouldn't add anything more about testing in this document. Maybe I would add some guidelines in contributing.md (e.g. if you write a function, write some unit tests for it; if you write a syndicator, write a few integration tests for it).
|
|
||
| Create an `.env` file in the root of the project, for example: | ||
| ### Mastodon syndicator |
There was a problem hiding this comment.
I wonder if we should dictate a particular syndicator here, or point to the documentation for the first-party syndicator plugins (which in turn perhaps need improved guidance)?
There was a problem hiding this comment.
As far as I know, the configuration for the Mastodon syndicator stays the same, no matter the user wants to just use Indiekit, or contribute the the syndicator itself.
So we could add something along these lines:
To know all the configuration options for this syndicator, refer to its README.md
| ``` | ||
|
|
||
| You can then start the server: | ||
| ### Environment variables |
There was a problem hiding this comment.
As mentioned, maybe this guidance should appear earlier in this document? Perhaps using PUBLICATION_URL as an example variable to set?
Happy to mention direnv, but the default means of setting variables should be using dotenv (perhaps to later be replaced with guidance that refers to Node’s native support for reading .env files).
Co-authored-by: Paul Robert Lloyd <[email protected]>
Co-authored-by: Paul Robert Lloyd <[email protected]>
Co-authored-by: Paul Robert Lloyd <[email protected]>
Co-authored-by: Paul Robert Lloyd <[email protected]>
paulrobertlloyd
force-pushed
the
main
branch
7 times, most recently
from
f94062a to
1996a3d
Compare
This PR moves some documentation from
contributing.mdto a newdevelopment.mdfile. This way we can keep summarizing all the way people can contribute to the project incontributing.md, and at the same time thoroughly explain how to setup a development environment indevelopment.md.I wouldn't say having a
development.mdfile is a standard practice, but I have encountered a fewdevelopment.mdin the wild (example 1, example 2) . It seems a good idea to me.I also created a
docker-compose.ymlto provide a convenient way to run a MongoDB database locally.