diff --git a/README.md b/README.md index 9a54f06..6a60b02 100644 --- a/README.md +++ b/README.md @@ -57,3 +57,176 @@ The end result is a directory structure that has everything you need to hit the └── env └── fully.qualified.domain.name.example ``` + +# Developing + +To change Cookiecutter templates get yourself an environment then make, test and commit your changes. First things first, the environment. + +## Environment + +Get yourself a Python virtual environment. In this example we're assuming you're running a Linux operating system and you'll be using [pyenv](https://github.com/pyenv/pyenv) to manage virtual environments. + +### pyenv + +- Install pyenv with what they are calling their automatic installer. Feel free to also read up on pyenv on their [GitHub project page](https://github.com/pyenv/pyenv). + ``` + curl https://pyenv.run | bash + ``` + +- Following the installer's instruction add at least the following commands to your `~/.bashrc` file + ``` + export PYENV_ROOT="$HOME/.pyenv" + command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH" + eval "$(pyenv init -)" + ``` + +- You will also likely want to add this line which will make sure pyenv auto-activates venvs when you navigate into certain directories. More on that down at [venv](#venv). + ``` + eval "$(pyenv virtualenv-init -)" + ``` + +- Also make sure `~/.bashrc` gets loaded for example by including this in a `~/.bash_profile` file + ``` + [[ -f ~/.bashrc ]] && . ~/.bashrc + ``` + +- Reload `~/.bashrc` + ``` + source ~/.bashrc + ``` + +### Python + +- Update pyenv's package list + ``` + pyenv update + ``` +- Pick a Python version you like, for example copy-paste `3.11.4`: + ``` + pyenv install --list | less + + ... + 3.10.12 + 3.11.0 + 3.11-dev + 3.11.1 + 3.11.2 + 3.11.3 + 3.11.4 + 3.12.0b2 + 3.12-dev + 3.13-dev + ... + ``` +- Install Python, wait for compilation to finish on your machine + ``` + pyenv install 3.11.4 + ``` + +### Repo + +- Clone this repo + ``` + git clone https://quico.space/Quico/py-cookiecutter-templates.git ~/py-cookiecutter-templates + ``` + +### venv + +- Create a virtual environment where `3.11.4` is the Python version you want to use in this venv and `cookiecutter-3.11.4` is the name of your venv. Adding or dropping the Python version from your venv name comes down to personal preference. + ``` + pyenv virtualenv 3.11.4 cookiecutter-3.11.4 + ``` + +- In your repo path `~/py-cookiecutter-templates` create a `.python-version` file to tell pyenv to always activate your desired venv when inside this dir. + ``` + cd ~/py-cookiecutter-templates + pyenv local cookiecutter-3.11.4 + ``` + pyenv will immediately prefix your shell's `${PS1}` prompt with the venv name. + ``` + (cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ + ``` + It will deactivate the venv and drop its prefix as soon as you navigate out of this dir. + ``` + (cookiecutter-3.11.4) [✔ 23:19 user@machine py-cookiecutter-templates]$ cd + [✔ 23:19 user@machine ~]$ + ``` + For now though stay in `~/py-cookiecutter-templates`, you're going to want to pip-install [cookiecutter](https://pypi.org/project/cookiecutter). + +- Upgrade `pip` + ``` + pip install --upgrade pip + ``` + +- Install [cookiecutter](https://pypi.org/project/cookiecutter) + ``` + pip install cookiecutter + ``` + +All done, your environment is set up. + +## Change + +Make some code changes, for example to the Docker Compose Cookiecutter template. When you're happy run your local Cookiecutter template to see how your changes are rendering. + +- Create `/tmp/cookiecutter-docker-compose` + ``` + mkdir '/tmp/cookiecutter-docker-compose' + ``` + +- Render a Docker Compose directory into your output directory, answer Cookiecutter's prompts: + ``` + # cookiecutter ~/py-cookiecutter-templates \ + --directory docker-compose \ + --output-dir /tmp/cookiecutter-docker-compose + + project_slug [dir-name]: mydir + service [mydir]: myservice + component_list [myservice]: mycomponent_one,mycomponent_two + context [ctx]: ux_novosibirsk + ``` + +- Observe that in `/tmp/cookiecutter-docker-compose` you now have your rendered Docker Compose dir: + ``` + # tree /tmp/cookiecutter-docker-compose + + /tmp/cookiecutter-docker-compose + └── mydir + ├── build-context + │   ├── mycomponent_one + │   │   ├── docker-data + │   │   ├── Dockerfile + │   │   └── extras + │   └── mycomponent_two + │   ├── docker-data + │   ├── Dockerfile + │   └── extras + ├── common-settings.yml + ├── docker-compose.override.yml + ├── docker-compose.yml + └── env + └── fqdn_context.env.example + ``` + +- For rapid testing you will most likely want to not type prompt answers repeatedly. Give them as command line arguments instead, also specify `--no-input` to suppress prompts: + ``` + cookiecutter ~/py-cookiecutter-templates \ + --no-input \ + --directory docker-compose \ + --output-dir /tmp/cookiecutter-docker-compose \ + project_slug=mydir \ + service=myservice \ + component_list=mycomponent_one,mycomponent_two \ + context=ux_novosibirsk + ``` + +## Commit prep + +When you're about ready to commit changes into this repo check the following bullet points. + +- Did you update the [Cookiecutter template README.md file](docker-compose/README.md), here for example for Docker Compose? + - Change in behavior? + - An updated example directory layout? + - Updated example file content? +- Did you commit a new completely rendered example directory structure into [docker-compose/examples](docker-compose/examples) dir? +- Did you change something that affects existing example directories? If so rerender them.