Add documentation about the new .tofu extension (#1841)

Signed-off-by: Ronny Orot <ronny.orot@gmail.com>

website/docs/cli/commands/index.mdx

@@ -65,8 +65,9 @@ command's page for details.
 ## Switching working directory with `-chdir`
 
 The usual way to run OpenTofu is to first switch to the directory containing
-the `.tf` files for your root module (for example, using the `cd` command), so
-that OpenTofu will find those files automatically without any extra arguments.
+the `.tf` or `.tofu` files for your root module (for example, using the `cd`
+command), so that OpenTofu will find those files automatically without any
+extra arguments.
 
 In some cases though — particularly when wrapping OpenTofu in automation
 scripts — it can be convenient to run OpenTofu from a different directory than

website/docs/cli/commands/plan.mdx

@@ -314,9 +314,10 @@ The available options are:
 
   OpenTofu will allow any filename for the plan file, but a typical
   convention is to name it `tfplan`. **Do not** name the file with a suffix
-  that OpenTofu recognizes as another file format; if you use a `.tf` suffix
-  then OpenTofu will try to interpret the file as a configuration source
-  file, which will then cause syntax errors for subsequent commands.
+  that OpenTofu recognizes as another file format; if you use a `.tf` or
+  `.tofu` suffix then OpenTofu will try to interpret the file as a
+  configuration source file, which will then cause syntax errors for subsequent
+  commands.
 
   The generated file is not in any standard format intended for consumption
   by other software, but the file _does_ contain your full configuration,

website/docs/cli/commands/test/index.mdx

@@ -44,8 +44,8 @@ the required conditions (assertions) are met. Once the test is complete, OpenTof
 
 Usage: `tofu test [options]`.
 
-This command will execute all `*.tftest.hcl` files in the current directory or in a directory called `tests`. You can
-customize this behavior using the [options](#options) below.
+This command will execute all `*.tftest.hcl`, `*.tftest.json`, `*.tofutest.hcl`, and `*.tofutest.json` files in the
+current directory or in a directory called `tests`. You can customize this behavior using the [options](#options) below.
 
 :::info Example
 
@@ -67,6 +67,22 @@ below.
 
 :::
 
+## Extension Precedence
+When both `.tftest.hcl` and `.tofutest.hcl` files with the same base name are present in a
+directory, OpenTofu will prioritize the `.tofutest.hcl` file and ignore the `.tftest.hcl` file.
+For example:
+
+- If both `main.tftest.hcl` and `main.tofutest.hcl` exist in the same directory, OpenTofu will
+only load `main.tofutest.hcl` and ignore `main.tftest.hcl`.
+
+This ensures that `.tofu` files always take precedence over `.tf` files when
+both are available. This scenario can be useful for module authors who want
+their modules to support both OpenTofu and Terraform and want to create different tests for each.
+
+The same rule applies to JSON-based test files:
+- if both `main.tftest.json` and `main.tofutest.json` exist in the same directory, OpenTofu will
+only load `main.tofutest.json` and ignore `main.tftest.json`.
+
 ## Options
 
 * `-test-directory=path` Set the test directory (default: "tests"). OpenTofu will search for test files in the specified
@@ -124,7 +140,7 @@ times to run more than one test file.
 
 :::
 
-## The `*.tftest.hcl` file structure
+## The `*.tftest.hcl` / `*.tofutest.hcl` file structure
 
 The testing language of OpenTofu is similar to the main OpenTofu language and uses the same block structure.
 

website/docs/cli/config/config-file.mdx

@@ -43,8 +43,8 @@ Any such file should follow the naming pattern `*.tfrc`.
 
 ## Configuration File Syntax
 
-The configuration file uses the same _HCL_ syntax as `.tf` files, but with
-different attributes and blocks. The following example illustrates the
+The configuration file uses the same _HCL_ syntax as `.tf` and `.tofu` files,
+but with different attributes and blocks. The following example illustrates the
 general syntax; see the following section for information on the meaning
 of each of these settings:
 

website/docs/language/files/dependency-lock.mdx

@@ -39,8 +39,8 @@ to ensure that OpenTofu will always select the same module version.
 The dependency lock file is a file that belongs to the configuration as a
 whole, rather than to each separate module in the configuration. For that reason
 OpenTofu creates it and expects to find it in your current working directory
-when you run OpenTofu, which is also the directory containing the `.tf` files
-for the root module of your configuration.
+when you run OpenTofu, which is also the directory containing the `.tf` or
+`.tofu` files for the root module of your configuration.
 
 The lock file is always named `.terraform.lock.hcl`, and this name is intended
 to signify that it is a lock file for various items that OpenTofu caches in
@@ -54,8 +54,8 @@ would discuss potential changes to your configuration itself.
 
 The dependency lock file uses the same low-level syntax as the main OpenTofu
 language, but the dependency lock file is not itself an OpenTofu language
-configuration file. It is named with the suffix `.hcl` instead of `.tf` in
-order to signify that difference.
+configuration file. It is named with the suffix `.hcl` instead of `.tf` or
+`.tofu` in order to signify that difference.
 
 ## Dependency Installation Behavior
 

website/docs/language/files/index.mdx

@@ -8,13 +8,26 @@ description: >-
 
 ## File Extension
 
-Code in the OpenTofu language is stored in plain text files with the `.tf` file
-extension. There is also
-[a JSON-based variant of the language](../../language/syntax/json.mdx) that is named with
-the `.tf.json` file extension.
+Code in the OpenTofu language is stored in plain text files with the `.tf`
+or `.tofu` file extensions. There is also
+[a JSON-based variant of the language](../../language/syntax/json.mdx) that is
+named with the `.tf.json` or `.tofu.json` file extensions.
 
 Files containing OpenTofu code are often called _configuration files._
 
+### Extension Precedence
+
+When both `.tf` and `.tofu` files with the same base name are present in a
+directory, OpenTofu will prioritize the `.tofu` file and ignore the `.tf` file.
+For example:
+
+- If both `foo.tf` and `foo.tofu` exist in the same directory, OpenTofu will
+only load `foo.tofu` and ignore `foo.tf`.
+
+This ensures that `.tofu` files always take precedence over `.tf` files when
+both are available. This scenario can be useful for module authors who want
+their modules to support both OpenTofu and Terraform.
+
 ## Text Encoding
 
 Configuration files must always use UTF-8 encoding, and by convention
@@ -23,8 +36,8 @@ line endings (CRLF), though both are accepted.
 
 ## Directories and Modules
 
-A _module_ is a collection of `.tf` and/or `.tf.json` files kept together in a
-directory.
+A _module_ is a collection of one or many `.tf`, `.tf.json`, `.tofu`,
+`.tofu.json` files kept together in a directory.
 
 An OpenTofu module only consists of the top-level configuration files in a
 directory; nested directories are treated as completely separate modules, and

website/docs/language/files/override.mdx

@@ -6,10 +6,10 @@ description: >-
 
 # Override Files
 
-OpenTofu normally loads all of the `.tf` and `.tf.json` files within a
-directory and expects each one to define a distinct set of configuration
-objects. If two files attempt to define the same object, OpenTofu returns
-an error.
+OpenTofu normally loads all of the `.tf`, `.tofu`, `.tf.json` and `.tofu.json`
+files within a directory and expects each one to define a distinct set of
+configuration objects. If two files attempt to define the same object, OpenTofu
+returns an error.
 
 In some rare cases, it is convenient to be able to override specific portions
 of an existing configuration object in a separate file. For example, a
@@ -18,9 +18,20 @@ could be partially overridden using a programmatically-generated file
 in JSON syntax.
 
 For these rare situations, OpenTofu has special handling of any configuration
-file whose name ends in `_override.tf` or `_override.tf.json`. This special
-handling also applies to a file named literally `override.tf` or
-`override.tf.json`.
+file whose name ends in `_override.tf`, `_override.tofu`, `_override.tf.json`
+or `_override.tofu.json`. This special handling also applies to a file named
+literally `override.tf`, `override.tofu`, `override.tf.json` or
+`override.tofu.json`.
+
+:::note
+[Extension Precedence](./index.mdx#extension-precedence) is important when
+dealing with override files. If both `foo_override.tf` and `foo_override.tofu`
+exist in the same directory, OpenTofu will only load `foo_override.tofu` and
+disregard `foo_override.tf`. The same rule applies to JSON-based files - if
+both `foo_override.tofu.json` and `foo_override.tf.json` exist in the same
+directory, OpenTofu will only load `foo_override.tofu.json` and ignore
+`foo_override.tf.json`.
+:::
 
 OpenTofu initially skips these _override files_ when loading configuration,
 and then afterwards processes each one in turn (in lexicographical order). For

website/docs/language/modules/develop/index.mdx

@@ -11,9 +11,9 @@ You can use modules to create lightweight abstractions, so that you can
 describe your infrastructure in terms of its architecture, rather than
 directly in terms of physical objects.
 
-The `.tf` files in your working directory when you run [`tofu plan`](../../../cli/commands/plan.mdx)
-or [`tofu apply`](../../../cli/commands/apply.mdx) together form the _root_
-module. That module may [call other modules](../../../language/modules/syntax.mdx#calling-a-child-module)
+The `.tf` and/or `.tofu` files in your working directory when you run
+[`tofu plan`](../../../cli/commands/plan.mdx) or [`tofu apply`](../../../cli/commands/apply.mdx)
+together form the _root_ module. That module may [call other modules](../../../language/modules/syntax.mdx#calling-a-child-module)
 and connect them together by passing output values from one to input values
 of another.
 

website/docs/language/modules/index.mdx

@@ -7,8 +7,8 @@ description: >-
 # Modules
 
 _Modules_ are containers for multiple resources that are used together. A module
-consists of a collection of `.tf` and/or `.tf.json` files kept together in a
-directory.
+consists of a collection of `.tf`, `.tofu`, `.tf.json`, and/or `.tofu.json`
+files that are kept together in a directory.
 
 Modules are the main way to package and reuse resource configurations with
 OpenTofu.
@@ -16,8 +16,8 @@ OpenTofu.
 ## The Root Module
 
 Every OpenTofu configuration has at least one module, known as its
-_root module_, which consists of the resources defined in the `.tf` files in
-the main working directory.
+_root module_, which consists of the resources defined in the `.tf` or `.tofu`
+files in the main working directory.
 
 ## Child Modules
 

website/docs/language/modules/syntax.mdx

@@ -10,8 +10,8 @@ description: >-
 A _module_ is a container for multiple resources that are used together.
 
 Every OpenTofu configuration has at least one module, known as its
-_root module_, which consists of the resources defined in the `.tf` files in
-the main working directory.
+_root module_, which consists of the resources defined in the `.tf` and `.tofu`
+files in the main working directory.
 
 A module can call other modules, which lets you include the child module's
 resources into the configuration in a concise way. Modules

website/docs/language/syntax/json.mdx

@@ -20,8 +20,8 @@ be expressed in native syntax can also be expressed in JSON syntax, but some
 constructs are more complex to represent in JSON due to limitations of the
 JSON grammar.
 
-OpenTofu expects native syntax for files named with a `.tf` suffix, and
-JSON syntax for files named with a `.tf.json` suffix.
+OpenTofu expects native syntax for files named with a `.tf` or `.tofu` suffix,
+and JSON syntax for files named with a `.tf.json` or `.tofu.json` suffix.
 
 The low-level JSON syntax, just as with the native syntax, is defined in terms
 of a specification called _HCL_. It is not necessary to know all of the details
@@ -30,6 +30,19 @@ summarizes the most important differences between native and JSON syntax.
 If you are interested, you can find a full definition of HCL's JSON syntax
 in [its specification](https://github.com/hashicorp/hcl/blob/main/json/spec.md).
 
+### Extension Precedence
+
+When both `.tf.json` and `.tofu.json` files with the same base name are present
+in a directory, OpenTofu will prioritize the `.tofu.json` file and ignore the
+`.tf.json` file. For example:
+
+- If both `foo.tf.json` and `foo.tofu.json` exist in the same directory,
+OpenTofu will only load `foo.tofu.json` and ignore `foo.tf.json`.
+
+This ensures that `.tofu.json` files always take precedence over `.tf.json`
+files when both are available. This scenario can be useful for module authors
+who want their modules to support both OpenTofu and Terraform.
+
 ## JSON File Structure
 
 At the root of any JSON-based OpenTofu configuration is a JSON object. The