Skip to content

Commit ec75fd4

Browse files
stasadevstasadev
committed
feat: first time setup
1 parent 8d4224c commit ec75fd4

File tree

5 files changed

+168
-23
lines changed

5 files changed

+168
-23
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
## The Issue
22

3-
- #<issue number>
3+
- Fixes #REPLACE_ME_WITH_RELATED_ISSUE_NUMBER
44

55
<!-- Provide a brief description of the issue. -->
66

77
## How This PR Solves The Issue
88

9+
<!-- Describe the key change(s) in this PR that address the issue above. -->
10+
911
## Manual Testing Instructions
1012

13+
<!-- If this PR changes logic, consider adding additional steps or context to the instructions below. -->
14+
1115
```bash
12-
ddev add-on get https://github.com/<user>/<repo>/tarball/<branch>
16+
ddev add-on get https://github.com/ddev/ddev-addon-template/tarball/refs/pull/REPLACE_ME_WITH_THIS_PR_NUMBER/head
1317
ddev restart
1418
```
1519

‎.github/scripts/first-time-setup.sh‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#!/usr/bin/env bash
2+
3+
set -o errexit
4+
set -o nounset
5+
set -o pipefail
6+
7+
GITHUB_REPOSITORY=${1?Error: Please pass repo org/name, e.g. ddev/ddev-addon-name}
8+
9+
FULL_REPO_NAME="$GITHUB_REPOSITORY"
10+
REPO_NAME="${GITHUB_REPOSITORY##*/}"
11+
USER_NAME="${GITHUB_REPOSITORY%%/*}"
12+
REPLACE_UNDERSCORES=${REPO_NAME//_/-}
13+
NO_PREFIX_NAME="${REPLACE_UNDERSCORES#ddev-}"
14+
LOWERCASE_NAME="${NO_PREFIX_NAME,,}"
15+
ENV_VARIABLE_NAME_DOCKER_IMAGE=$(echo "${LOWERCASE_NAME//-/_}_DOCKER_IMAGE" | tr '[:lower:]' '[:upper:]')
16+
PRETTY_NAME=$(echo "${LOWERCASE_NAME}" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) substr($i,2)} 1')
17+
18+
echo "[![add-on registry](https://img.shields.io/badge/DDEV-Add--on_Registry-blue)](https://addons.ddev.com)
19+
[![tests](https://github.com/$FULL_REPO_NAME/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/$FULL_REPO_NAME/actions/workflows/tests.yml?query=branch%3Amain)
20+
[![last commit](https://img.shields.io/github/last-commit/$FULL_REPO_NAME)](https://github.com/$FULL_REPO_NAME/commits)
21+
[![release](https://img.shields.io/github/v/release/$FULL_REPO_NAME)](https://github.com/$FULL_REPO_NAME/releases/latest)
22+
23+
# DDEV $PRETTY_NAME
24+
25+
## Overview
26+
27+
This add-on integrates $PRETTY_NAME into your [DDEV](https://ddev.com/) project.
28+
29+
## Installation
30+
31+
\`\`\`bash
32+
ddev add-on get $FULL_REPO_NAME
33+
ddev restart
34+
\`\`\`
35+
36+
After installation, make sure to commit the \`.ddev\` directory to version control.
37+
38+
## Usage
39+
40+
| Command | Description |
41+
| ------- | ----------- |
42+
| \`ddev describe\` | View service status and used ports for $PRETTY_NAME |
43+
| \`ddev logs -s $LOWERCASE_NAME\` | Check $PRETTY_NAME logs |
44+
45+
## Advanced Customization
46+
47+
To change the Docker image:
48+
49+
\`\`\`bash
50+
51+
ddev dotenv set .ddev/.env.$LOWERCASE_NAME --$LOWERCASE_NAME-docker-image="busybox:stable"
52+
ddev add-on get $FULL_REPO_NAME
53+
ddev restart
54+
\`\`\`
55+
56+
Make sure to commit the \`.ddev/.env.$LOWERCASE_NAME\` file to version control.
57+
58+
All customization options (use with caution):
59+
60+
| Variable | Flag | Default |
61+
| -------- | ---- | ------- |
62+
| \`$ENV_VARIABLE_NAME_DOCKER_IMAGE\` | \`--$LOWERCASE_NAME-docker-image\` | \`busybox:stable\` |
63+
64+
## Credits
65+
66+
**Contributed and maintained by [@$USER_NAME](https://github.com/$USER_NAME)**" > README.md
67+
68+
mv docker-compose.addon-template.yaml "docker-compose.$LOWERCASE_NAME.yaml"
69+
sed -i "s|addon-template|$LOWERCASE_NAME|g" "docker-compose.$LOWERCASE_NAME.yaml"
70+
sed -i "s|ADDON_TEMPLATE_DOCKER_IMAGE|$ENV_VARIABLE_NAME_DOCKER_IMAGE|g" "docker-compose.$LOWERCASE_NAME.yaml"
71+
72+
sed -i "s|ddev/ddev-addon-template|$FULL_REPO_NAME|g" tests/test.bats
73+
sed -i "s|ddev/ddev-addon-template|$FULL_REPO_NAME|g" .github/PULL_REQUEST_TEMPLATE.md
74+
75+
echo "name: $LOWERCASE_NAME
76+
77+
project_files:
78+
- docker-compose.$LOWERCASE_NAME.yaml
79+
80+
ddev_version_constraint: '>= v1.24.3'" > install.yaml
81+
82+
rm -f README_DEBUG.md
83+
rm -f .github/workflows/first-time-setup.yml
84+
rm -rf images
85+
rm -rf .github/scripts

‎.github/workflows/first-time-setup.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: first-time-setup
2+
3+
on:
4+
push:
5+
6+
# Only keep latest run of this workflow and cancel any previous runs
7+
concurrency:
8+
group: first-time-setup
9+
cancel-in-progress: true
10+
11+
permissions:
12+
contents: write
13+
14+
jobs:
15+
first-time-setup:
16+
if: ${{ !github.event.repository.is_template }}
17+
18+
runs-on: "ubuntu-latest"
19+
20+
steps:
21+
- name: Checkout code
22+
uses: actions/checkout@v4
23+
24+
- name: Update files
25+
run: ./.github/scripts/first-time-setup.sh "$GITHUB_REPOSITORY"
26+
27+
- name: Commit and push changes
28+
run: |
29+
git config --global user.name "github-actions[bot]"
30+
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
31+
git add .
32+
git commit -m "First time setup"
33+
git push

‎README.md‎

Lines changed: 42 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,17 @@
33
[![last commit](https://img.shields.io/github/last-commit/ddev/ddev-addon-template)](https://github.com/ddev/ddev-addon-template/commits)
44
[![release](https://img.shields.io/github/v/release/ddev/ddev-addon-template)](https://github.com/ddev/ddev-addon-template/releases/latest)
55

6-
# DDEV add-on template <!-- omit in toc -->
6+
# DDEV Add-on Template <!-- omit in toc -->
77

8-
* [What is DDEV add-on template?](#what-is-ddev-add-on-template)
8+
* [What is DDEV Add-on Template?](#what-is-ddev-add-on-template)
9+
* [TL;DR](#tldr)
910
* [Components of the repository](#components-of-the-repository)
1011
* [Getting started](#getting-started)
11-
* [How to debug in Github Actions](./README_DEBUG.md)
12+
* [How to debug in Github Actions](#how-to-debug-in-github-actions)
13+
* [Resources](#resources)
14+
* [Credits](#credits)
1215

13-
## What is DDEV add-on template?
16+
## What is DDEV Add-on Template?
1417

1518
This repository is a template for providing [DDEV](https://ddev.readthedocs.io) add-ons and services.
1619

@@ -20,6 +23,19 @@ This repository is a quick way to get started. You can create a new repo from th
2023

2124
![template button](images/template-button.png)
2225

26+
## TL;DR
27+
28+
1. Click the green `Use this template button` (top right) > `Create a new repository`.
29+
2. Name your repository using the `ddev-` prefix (e.g. `ddev-foobar`).
30+
3. Add a meaningful description with relevant keywords for discoverability.
31+
4. Click `Create repository` and wait ~1 minute for the automated `First time setup` commit.
32+
5. Clone your repository locally (use the green <> Code button for the URL).
33+
6. Prepare your add-on files and tests, see [Getting started](#getting-started) for details.
34+
7. Create a new PR for review and discussion (avoid committing directly to `main`, as that bypasses the collaborative process).
35+
8. Merge or squash your PR into `main` (squash is preferred for a cleaner commit history).
36+
9. Create a new [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).
37+
10. When ready to share, make your add-on discoverable by adding the `ddev-get` [topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics).
38+
2339
## Components of the repository
2440

2541
* The fundamental contents of the add-on service or other component. For example, in this template there is a [docker-compose.addon-template.yaml](docker-compose.addon-template.yaml) file.
@@ -31,27 +47,34 @@ This repository is a quick way to get started. You can create a new repo from th
3147

3248
1. Choose a good descriptive name for your add-on. It should probably start with "ddev-" and include the basic service or functionality. If it's particular to a specific CMS, perhaps `ddev-<CMS>-servicename`.
3349
2. Create the new template repository by using the template button.
34-
3. Globally replace "addon-template" with the name of your add-on.
35-
4. Add the files that need to be added to a DDEV project to the repository. For example, you might replace `docker-compose.addon-template.yaml` with the `docker-compose.*.yaml` for your recipe.
36-
5. Update the `install.yaml` to give the necessary instructions for installing the add-on:
50+
3. Add the files that need to be added to a DDEV project to the repository. If your add-on does not add a new service, remove `docker-compose.<addon-name>.yaml` file.
51+
4. Update the `install.yaml` to give the necessary instructions for installing the add-on:
3752

3853
* The fundamental line is the `project_files` directive, a list of files to be copied from this repo into the project `.ddev` directory.
3954
* You can optionally add files to the `global_files` directive as well, which will cause files to be placed in the global `.ddev` directory, `~/.ddev`.
4055
* Finally, `pre_install_commands` and `post_install_commands` are supported. These can use the host-side environment variables documented [in DDEV docs](https://ddev.readthedocs.io/en/stable/users/extend/custom-commands/#environment-variables-provided).
4156

42-
6. Update `tests/test.bats` to provide a reasonable test for your repository. Tests will run automatically on every push to the repository, and periodically each night. Please make sure to address test failures when they happen. Others will be depending on you. Bats is a testing framework that just uses Bash. To run a Bats test locally, you have to install [bats-core](https://bats-core.readthedocs.io/en/stable/installation.html) and its [libraries](https://github.com/ztombol/bats-docs) first. Then you download your add-on, and finally run `bats ./tests/test.bats` within the root of the uncompressed directory. To learn more about Bats see the [documentation](https://bats-core.readthedocs.io/en/stable/).
43-
7. When everything is working, including the tests, you can push the repository to GitHub.
44-
8. Create a [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) on GitHub.
45-
9. Test manually with `ddev add-on get <owner/repo>`.
46-
10. You can test PRs with `ddev add-on get https://github.com/<user>/<repo>/tarball/<branch>`.
47-
11. You can test add-ons locally without GitHub by downloading them, making changes and running `ddev add-on get /path/to/add-on-directory`.
48-
12. Update the `README.md` header, adding the machine name of the add-on, for example `# ddev-redis`, not `# DDEV Redis`.
49-
13. Update the `README.md` to describe the add-on, how to use it, and how to contribute. If there are any manual actions that have to be taken, please explain them. If it requires special configuration of the using project, please explain how to do those. Examples in [ddev/ddev-solr](https://github.com/ddev/ddev-solr), [ddev/ddev-memcached](https://github.com/ddev/ddev-memcached), and (advanced) [ddev-platformsh](https://github.com/ddev/ddev-platformsh).
50-
14. Add a good short description to your repo, and add the [topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) "ddev-get". It will immediately be added to the list provided by `ddev add-on list --all`.
51-
15. When it has matured you will hopefully want to have it become an "official" maintained add-on. Open an issue in the [DDEV queue](https://github.com/ddev/ddev/issues) for that.
57+
5. Update `tests/test.bats` to provide a reasonable test for your repository. In most cases, you only need to modify the `health_checks()` function. Tests will run automatically on every push to the repository, and periodically each night. Please make sure to address test failures when they happen. Others will be depending on you. Bats is a testing framework that just uses Bash. To run a Bats test locally, you have to install [bats-core](https://bats-core.readthedocs.io/en/stable/installation.html) and its [libraries](https://github.com/ztombol/bats-docs) first. Then you download your add-on, and finally run `bats ./tests/test.bats` within the root of the uncompressed directory. To learn more about Bats see the [documentation](https://bats-core.readthedocs.io/en/stable/).
58+
6. When everything is working, including the tests, you can push the repository to GitHub.
59+
7. Create a [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) on GitHub.
60+
8. Test manually with `ddev add-on get <owner/repo>`.
61+
9. You can test PRs with `ddev add-on get https://github.com/<user>/<repo>/tarball/<branch>` or `https://github.com/<user>/<repo>/tarball/refs/pull/<pr-number>/head`.
62+
10. You can test add-ons locally without GitHub by downloading them, making changes and running `ddev add-on get /path/to/add-on-directory`.
63+
11. Update the `README.md` to describe the add-on, how to use it, and how to contribute. If there are any manual actions that have to be taken, please explain them. If it requires special configuration of the using project, please explain how to do those. Examples in [ddev/ddev-solr](https://github.com/ddev/ddev-solr), [ddev/ddev-memcached](https://github.com/ddev/ddev-memcached), and (advanced) [ddev-platformsh](https://github.com/ddev/ddev-platformsh).
64+
12. Add a good short description to your repo, and add the `ddev-get` [topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). It will immediately be added to the list provided by `ddev add-on list --all`.
65+
13. When it has matured you will hopefully want to have it become an "official" maintained add-on. Open an issue in the [DDEV queue](https://github.com/ddev/ddev/issues) for that.
66+
67+
## How to debug in Github Actions
68+
69+
See [full instructions](./README_DEBUG.md).
70+
71+
## Resources
5272

53-
Add-ons were covered in [DDEV Add-ons: Creating, maintaining, testing](https://www.youtube.com/watch?v=TmXqQe48iqE) (part of the [DDEV Contributor Live Training](https://ddev.com/blog/contributor-training)).
73+
* [DDEV Add-ons: Creating, maintaining, testing](https://www.youtube.com/watch?v=TmXqQe48iqE) (part of the [DDEV Contributor Live Training](https://ddev.com/blog/contributor-training))
74+
* [Advanced Add-On Techniques](https://ddev.com/blog/advanced-add-on-contributor-training/)
75+
* [DDEV docs](https://ddev.readthedocs.io/en/stable/users/extend/additional-services/)
76+
* [DDEV Add-on Registry](https://addons.ddev.com/)
5477

55-
Note that more advanced techniques are discussed in [Advanced Add-On Techniques](https://ddev.com/blog/advanced-add-on-contributor-training/) and [DDEV docs](https://ddev.readthedocs.io/en/stable/users/extend/additional-services/).
78+
## Credits
5679

5780
**Contributed and maintained by `@CONTRIBUTOR`**

‎docker-compose.addon-template.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@
33
services:
44
addon-template:
55
container_name: ddev-${DDEV_SITENAME}-addon-template
6-
image: busybox:stable
6+
image: ${ADDON_TEMPLATE_DOCKER_IMAGE:-busybox:stable}
77
command: tail -f /dev/null
88
restart: "no"
99
# These labels ensure this service is discoverable by DDEV.
1010
labels:
1111
com.ddev.site-name: ${DDEV_SITENAME}
12-
com.ddev.approot: $DDEV_APPROOT
12+
com.ddev.approot: ${DDEV_APPROOT}
1313

1414
volumes:
1515
- ".:/mnt/ddev_config"

0 commit comments

Comments
 (0)