docs: add docs for deprecating a feature (#74)

* docs: add docs for deprecating a feature

* Update .github/MAINTAINERS_GUIDE.md

Co-authored-by: Eden Zimbelman <[email protected]>

---------

Co-authored-by: Eden Zimbelman <[email protected]>

Author: mwbrooks

.github/MAINTAINERS_GUIDE.md

@@ -578,6 +578,18 @@ Testing in our CI setup uses changes to these files when creating test builds.
 Many good things come to an end. This can sometimes include commands and flags.
 When commands or flags need to be removed, follow these steps:
 
+<details>
+<summary>Deprecating features</summary>
+
+- Public functionality should be deprecated on the next `semver:major` version
+  - Add the comment `// DEPRECATED(semver:major): Description about the deprecation and migration path`
+  - Print a warning `PrintWarning("DEPRECATED: Description about the deprecation and migration path")`
+- Internal functionality can be deprecated anytime
+  - Add the comment `// DEPRECATED: Description about the deprecation and migration path`
+- Please add deprecation comments generously to help the next person completely remove the feature and tests
+
+</details>
+
 <details>
 <summary>Deprecating commands</summary>
 

internal/config/project.go

@@ -316,7 +316,7 @@ func (c *ProjectConfig) GetProjectDirPath() (string, error) {
 	if _, err := c.fs.Stat(projectHooksJSONPath); os.IsNotExist(err) {
 
 		// Fallback check for slack.json and .slack/slack.json file
-		// TODO(semver:major): remove both fallbacks next major release
+		// DEPRECATED(semver:major): remove both fallbacks next major release
 		projectSlackJSONPath := filepath.Join(currentDir, "slack.json")
 		if _, err := c.fs.Stat(projectSlackJSONPath); err == nil {
 			return currentDir, nil

internal/pkg/create/create_test.go

@@ -129,15 +129,15 @@ func Test_Create_installProjectDependencies(t *testing.T) {
 			},
 			unexpectedOutputs: []string{
 				"Found project-name/.slack/hooks.json", // Behind bolt experiment
-				"project-name/slack.json",              // TODO(semver:major) Deprecated
+				"project-name/slack.json",              // DEPRECATED(semver:major): Now use hooks.json
 			},
 			expectedVerboseOutputs: []string{
 				"Detected a project using Deno",
 			},
 		},
 		"When no bolt experiment and slack.json exists, should output adding .slack and caching steps": {
 			existingFiles: map[string]string{
-				"slack.json": "{}", // TODO(semver:major) Included with the template (deprecated path)
+				"slack.json": "{}", // DEPRECATED(semver:major): Included with the template (deprecated path)
 			},
 			expectedOutputs: []string{
 				"Added project-name/.slack",
@@ -188,7 +188,7 @@ func Test_Create_installProjectDependencies(t *testing.T) {
 			},
 			expectedOutputs: []string{
 				"Added project-name/.slack",
-				"Found project-name/slack.json", // TODO(semver:major) Deprecated
+				"Found project-name/slack.json", // DEPRECATED(semver:major): Now use hooks.json
 				"Cached dependencies with deno cache import_map.json",
 			},
 			expectedVerboseOutputs: []string{

internal/shared/clients.go

@@ -200,7 +200,7 @@ func (c *ClientFactory) InitSDKConfig(ctx context.Context, dirPath string) error
 			break
 		}
 		// Then, fallback to hooks in the deprecated project slack.json file
-		// TODO(semver:major) - Drop support on the next major
+		// DEPRECATED(semver:major) - Drop support on the next major
 		hooksJSONFilePath = filepath.Join(dirPath, "slack.json")
 		info, err = c.Fs.Stat(hooksJSONFilePath)
 		if err == nil && !info.IsDir() {
@@ -210,7 +210,7 @@ func (c *ClientFactory) InitSDKConfig(ctx context.Context, dirPath string) error
 		// Next, search for the hooks files in the outdated path
 		// .slack/slack.json and display an error that this path
 		// is deprecated
-		// TODO(semver:major) - Drop support on the next major
+		// DEPRECATED(semver:major) - Drop support on the next major
 		hooksJSONFilePath = filepath.Join(dirPath, ".slack", "slack.json")
 		info, err = c.Fs.Stat(hooksJSONFilePath)
 		if err == nil && !info.IsDir() {
@@ -220,7 +220,7 @@ func (c *ClientFactory) InitSDKConfig(ctx context.Context, dirPath string) error
 		// Next, search for the hooks files in the outdated path
 		// .slack/cli.json and display an error that this path
 		// is deprecated
-		// TODO(semver:major) - Drop support on the next major
+		// DEPRECATED(semver:major) - Drop support on the next major
 		hooksJSONFilePath = filepath.Join(dirPath, ".slack", "cli.json")
 		info, err = c.Fs.Stat(hooksJSONFilePath)
 		if err == nil && !info.IsDir() {