From 6de23c546f4091ac59f6d617fbc83b30f08c7937 Mon Sep 17 00:00:00 2001
From: blam <ben@blam.sh>
Date: Fri, 17 Mar 2023 13:31:02 +0100
Subject: [PATCH] chore: naming conventions for github actions

Signed-off-by: blam <ben@blam.sh>
---
 .../software-templates/writing-custom-actions.md  | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md
index 7a841dfd0e..93ea23cdbd 100644
--- a/docs/features/software-templates/writing-custom-actions.md
+++ b/docs/features/software-templates/writing-custom-actions.md
@@ -31,7 +31,7 @@ import { z } from 'zod';
 
 export const createNewFileAction = () => {
   return createTemplateAction({
-    id: 'mycompany:create-file',
+    id: 'file:create',
     schema: {
       input: z.object({
         contents: z.string().describe('The contents of the file'),
@@ -75,7 +75,7 @@ import { writeFile } from 'fs';
 
 export const createNewFileAction = () => {
   return createTemplateAction<{ contents: string; filename: string }>({
-    id: 'mycompany:create-file',
+    id: 'file:create',
     schema: {
       input: {
         required: ['contents', 'filename'],
@@ -107,6 +107,17 @@ export const createNewFileAction = () => {
 };
 ```
 
+#### A note on naming conventions
+
+Try to keep names consistent for both your own custom actions, and any actions contributed to open source. We've found that a seperation of `:` and using a verb as the last part of the name works well.
+We follow `provider:entity:verb` or as close to this as possible for our built in actions. For example, `github:actions:create` or `github:repo:create`.
+
+Also feel free to use your company name to namespace them if you prefer too, for example `acme:file:create`.
+
+Prefer to use `camelCase` over `pascalCase` for these actions if possible, which leads to better reading and writing of template entity definitions.
+
+> We're aware that theres some exceptions to this, but try to follow as close as possible. We'll be working on migrating these in the repository over time too.
+
 ### The context object
 
 When the action `handler` is called, we provide you a `context` as the only