feat: add a new .taskrc.yml to enable experiments

internal/experiments/experiments.go

@@ -8,6 +8,8 @@ import (
 	"slices"
 	"strings"
 
+	"gopkg.in/yaml.v3"
+
 	"github.com/Ladicle/tabwriter"
 	"github.com/joho/godotenv"
 	"github.com/spf13/pflag"
@@ -17,6 +19,15 @@ import (
 
 const envPrefix = "TASK_X_"
 
+var defaultConfigFilenames = []string{
+	".taskrc.yml",
+	".taskrc.yaml",
+}
+
+type ExperimentConfigFile struct {
+	Experiments map[string]string `yaml:"experiments"`
+}
+
 type Experiment struct {
 	Name    string
 	Enabled bool
@@ -32,8 +43,11 @@ var (
 	EnvPrecedence   Experiment
 )
 
+var experimentConfig ExperimentConfigFile
+
 func init() {
 	readDotEnv()
+	experimentConfig = readConfig()
 	GentleForce = New("GENTLE_FORCE")
 	RemoteTaskfiles = New("REMOTE_TASKFILES")
 	AnyVariables = New("ANY_VARIABLES", "1", "2")
@@ -45,7 +59,13 @@ func New(xName string, enabledValues ...string) Experiment {
 	if len(enabledValues) == 0 {
 		enabledValues = []string{"1"}
 	}
-	value := getEnv(xName)
+
+	value := experimentConfig.Experiments[xName]
+
+	if value == "" {
+		value = getEnv(xName)
+	}
+
 	return Experiment{
 		Name:    xName,
 		Enabled: slices.Contains(enabledValues, value),
@@ -65,7 +85,7 @@ func getEnv(xName string) string {
 	return os.Getenv(envName)
 }
 
-func getEnvFilePath() string {
+func getFilePath(filename string) string {
 	// Parse the CLI flags again to get the directory/taskfile being run
 	// We use a flagset here so that we can parse a subset of flags without exiting on error.
 	var dir, taskfile string
@@ -76,18 +96,18 @@ func getEnvFilePath() string {
 	_ = fs.Parse(os.Args[1:])
 	// If the directory is set, find a .env file in that directory.
 	if dir != "" {
-		return filepath.Join(dir, ".env")
+		return filepath.Join(dir, filename)
 	}
 	// If the taskfile is set, find a .env file in the directory containing the Taskfile.
 	if taskfile != "" {
-		return filepath.Join(filepath.Dir(taskfile), ".env")
+		return filepath.Join(filepath.Dir(taskfile), filename)
 	}
 	// Otherwise just use the current working directory.
-	return ".env"
+	return filename
 }
 
 func readDotEnv() {
-	env, _ := godotenv.Read(getEnvFilePath())
+	env, _ := godotenv.Read(getFilePath(".env"))
 	// If the env var is an experiment, set it.
 	for key, value := range env {
 		if strings.HasPrefix(key, envPrefix) {
@@ -96,6 +116,30 @@ func readDotEnv() {
 	}
 }
 
+func readConfig() ExperimentConfigFile {
+	var cfg ExperimentConfigFile
+
+	var content []byte
+	var err error
+	for _, filename := range defaultConfigFilenames {
+		path := getFilePath(filename)
+		content, err = os.ReadFile(path)
+		if err == nil {
+			break
+		}
+	}
+
+	if err != nil {
+		return ExperimentConfigFile{}
+	}
+
+	if err := yaml.Unmarshal(content, &cfg); err != nil {
+		return ExperimentConfigFile{}
+	}
+
+	return cfg
+}
+
 func printExperiment(w io.Writer, l *logger.Logger, x Experiment) {
 	l.FOutf(w, logger.Yellow, "* ")
 	l.FOutf(w, logger.Green, x.Name)

website/docs/experiments/experiments.mdx

@@ -3,6 +3,9 @@ slug: /experiments/
 sidebar_position: 6
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Experiments
 
 :::caution
@@ -39,23 +42,41 @@ Which method you use depends on how you intend to use the experiment:
 1. Prefixing your task commands with the relevant environment variable(s). For
    example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
    invocations of Task to test out experimental features.
-1. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
+2. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
    `.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
    for your personal environment.
 
    ```shell title="~/.bashrc"
    export TASK_X_FEATURE=1
    ```
 
-1. Creating a `.env` file in the same directory as your root Taskfile that
-   contains the relevant environment variable(s). This allows you to enable an
-   experimental feature at a project level. If you commit the `.env` file to
-   source control then other users of your project will also have these
-   experiments enabled.
-
-   ```shell title=".env"
-   TASK_X_FEATURE=1
-   ```
+3. Creating a `.env` or a `.task-experiments.yml` file in the same directory as
+   your root Taskfile.\
+   The `.env` file should contain the relevant environment
+   variable(s), while the `.task-experiments.yml` file should use a YAML format
+   where each experiment is defined as a key with a corresponding value.
+
+   This allows you to enable an experimental feature at a project level. If you
+   commit this file to source control, then other users of your project will
+   also have these experiments enabled.
+
+   If both files are present, the values in the `.task-experiments.yml` file
+   will take precedence.
+
+    <Tabs values={[ {label: '.task-experiments.yml', value: 'yaml'}, {label: '.env', value: 'env'}]}>
+     <TabItem value="yaml">
+       ```yaml title=".taskrc.yml"
+        experiments:
+          FEATURE: 1
+       ```
+     </TabItem>
+
+        <TabItem value="env">
+       ```shell title=".env"
+       TASK_X_FEATURE=1
+       ```
+     </TabItem>
+    </Tabs>
 
 ## Workflow
 

website/static/schema-taskrc.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Taskrc YAML Schema",
+  "description": "Schema for .taskrc files.",
+  "type": "object",
+  "properties": {
+    "experiments": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer"
+      }
+    }
+  },
+  "additionalProperties": false
+}