chore: update docs

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Developing the Terraform Provider for Forgejo
+
+## Requirements
+
+- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
+- [Go](https://golang.org/doc/install) >= 1.23
+
+## Building the Provider
+
+1. Clone the repository
+2. Enter the repository directory
+3. Build the provider using the `make install` command:
+
+```shell
+make install
+```
+
+### Directory Layout
+
+```shell
+terraform-provider-forgejo/
+├── docker/    # Example Forgejo installation for local development
+├── docs/      # Generated documentation
+├── examples/  # Provider usage examples
+├── internal/  # Provider source code and tests
+└── tools/     # Scripts for generating documentation
+```
+
+## Adding Dependencies
+
+This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
+Please see the Go documentation for the most up to date information about using Go modules.
+
+To add a new dependency `github.com/author/dependency` to your Terraform provider:
+
+```shell
+go get github.com/author/dependency
+go mod tidy
+```
+
+Then commit the changes to `go.mod` and `go.sum`.
+
+## Developing the Provider
+
+If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
+
+To compile the provider, run `make install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
+
+```shell
+make install
+```
+
+To generate or update documentation, run `make generate`.
+
+```shell
+make generate
+```
+
+In order to run the full suite of Acceptance tests, run `make testacc`.
+
+_Note:_ Acceptance tests create real resources, and often cost money to run.
+
+```shell
+make testacc
+```

README.md

@@ -1,128 +1,119 @@
-# Terraform Forgejo Provider
+# Terraform Provider for Forgejo
 
-This repository contains a Terraform provider for [Forgejo](https://forgejo.org/) — self-hosted lightweight software forge.
+This repository contains a [Terraform](https://www.terraform.io/) provider for [Forgejo](https://forgejo.org/) — self-hosted lightweight software forge.
 
 ## Contents
 
-It is in a **very early** stage and currently contains the following...
+The Forgejo Terraform Provider allows managing resources within Forgejo. It is in an **early** stage and currently provides the following...
 
 Resources:
 
 - `forgejo_organization` ([documentation](docs/resources/organization.md))
 - `forgejo_repository` ([documentation](docs/resources/repository.md))
+- `forgejo_user` ([documentation](docs/resources/user.md))
 
 Data Sources:
 
 - `forgejo_organization` ([documentation](docs/data-sources/organization.md))
 - `forgejo_repository` ([documentation](docs/data-sources/repository.md))
 - `forgejo_user` ([documentation](docs/data-sources/user.md))
 
-### Directory Layout
-
-```shell
-terraform-provider-forgejo/
-├── docker/    # Example Forgejo installation for local development
-├── docs/      # Generated documentation
-├── examples/  # Provider usage examples
-├── internal/  # Provider source code and tests
-└── tools/     # Scripts for generating documentation
-```
+## Using the Provider
 
-## Requirements
+Import the provider into your Terraform configuration:
 
-- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
-- [Go](https://golang.org/doc/install) >= 1.23
+```terraform
+terraform {
+  required_providers {
+    forgejo = {
+      source = "svalabs/forgejo"
+    }
+  }
+}
+```
 
-## Building the Provider
+There are two methods for authenticating to the Forgejo API: using an API token, or with username and password.
 
-1. Clone the repository
-2. Enter the repository directory
-3. Build the provider using the Go `install` command:
+It is recommended to supply an API token to authenticate with a given Forgejo host:
 
-```shell
-go install
+```terraform
+provider "forgejo" {
+  host      = "http://localhost:3000"
+  api_token = "1234567890abcdefghijklmnopqrstuvwxyz1234"
+  # alternatively, use the FORGEJO_API_TOKEN environment variable
+}
 ```
 
-## Adding Dependencies
+Alternatively, supply username and password to authenticate:
 
-This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
-Please see the Go documentation for the most up to date information about using Go modules.
+```terraform
+provider "forgejo" {
+  host     = "http://localhost:3000"
+  username = "admin"
+  password = "passw0rd"
+  # alternatively, use the FORGEJO_USERNAME / FORGEJO_PASSWORD environment variables
+}
+```
 
-To add a new dependency `github.com/author/dependency` to your Terraform provider:
+A personal repository can be created like so:
 
-```shell
-go get github.com/author/dependency
-go mod tidy
+```terraform
+resource "forgejo_repository" "example" {
+  name        = "new_personal_repo"
+  description = "Purely for testing..."
+}
 ```
 
-Then commit the changes to `go.mod` and `go.sum`.
-
-## Using the Provider
+A user repository can be created like so (requires administrative privileges):
 
 ```terraform
-terraform {
-  required_providers {
-    forgejo = {
-      source = "registry.terraform.io/svalabs/forgejo"
-    }
-  }
+resource "forgejo_user" "example" {
+  name = "new_user"
 }
 
-provider "forgejo" {
-  host      = "http://localhost:3000"
-  api_token = "1234567890abcdefghijklmnopqrstuvwxyz1234"
+resource "forgejo_repository" "example" {
+  owner       = forgejo_user.example.name
+  name        = "new_user_repo"
+  description = "Purely for testing..."
 }
+```
 
-data "forgejo_organization" "example" {
-  name = "existing_org"
-}
+A organization repository can be created like so:
 
+```terraform
 resource "forgejo_organization" "example" {
-  name        = "new_org"
-  full_name   = "Terraform Test Org"
-  description = "Purely for testing..."
-  website     = "https://forgejo.org/"
-  location    = "Mêlée Island"
-  visibility  = "private"
+  name = "new_org"
 }
 
-data "forgejo_repository" "example" {
-  owner = {}
-  name  = "existing_repo"
+resource "forgejo_repository" "example" {
+  owner       = forgejo_organization.example.name
+  name        = "new_org_repo"
+  description = "Purely for testing..."
 }
+```
+
+These examples create repositories with most attributes set to their default values. Many settings can be customized:
 
+```terraform
 resource "forgejo_repository" "example" {
-  owner          = {}
-  name           = "new_repo"
+  owner          = forgejo_organization.example.name
+  name           = "new_org_repo"
   description    = "Purely for testing..."
   private        = true
   default_branch = "dev"
   auto_init      = true
-}
+  trust_model    = "collaborator"
 
-data "forgejo_user" "example" {
-  login = "existing_user"
+  internal_tracker = {
+    enable_time_tracker                   = false
+    allow_only_contributors_to_track_time = false
+    enable_issue_dependencies             = false
+  }
 }
 ```
 
 Refer to the `examples/` directory for more usage examples.
 
-## Developing the Provider
-
-If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
-
-To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
-
-To generate or update documentation, run `make generate`.
-
-In order to run the full suite of Acceptance tests, run `make testacc`.
-
-_Note:_ Acceptance tests create real resources, and often cost money to run.
-
-```shell
-make testacc
-```
-
 ## Copyright and License
 
 Copyright (c) 2024 SVA System Vertrieb Alexander GmbH.

docs/data-sources/organization.md

@@ -16,7 +16,7 @@ Forgejo organization data source
 terraform {
   required_providers {
     forgejo = {
-      source = "registry.terraform.io/svalabs/forgejo"
+      source = "svalabs/forgejo"
     }
   }
 }
@@ -28,7 +28,6 @@ provider "forgejo" {
 data "forgejo_organization" "this" {
   name = "test1"
 }
-
 output "debug" {
   value = data.forgejo_organization.this
 }

docs/data-sources/repository.md

@@ -16,7 +16,7 @@ Forgejo repository data source
 terraform {
   required_providers {
     forgejo = {
-      source = "registry.terraform.io/svalabs/forgejo"
+      source = "svalabs/forgejo"
     }
   }
 }
@@ -31,16 +31,16 @@ data "forgejo_repository" "user" {
   }
   name = "user_test_repo_1"
 }
+output "user_debug" {
+  value = data.forgejo_repository.user
+}
+
 data "forgejo_repository" "org" {
   owner = {
     login = "test_org_1"
   }
   name = "org_test_repo_1"
 }
-
-output "user_debug" {
-  value = data.forgejo_repository.user
-}
 output "org_debug" {
   value = data.forgejo_repository.org
 }

docs/data-sources/user.md

@@ -16,7 +16,7 @@ Forgejo user data source
 terraform {
   required_providers {
     forgejo = {
-      source = "registry.terraform.io/svalabs/forgejo"
+      source = "svalabs/forgejo"
     }
   }
 }
@@ -28,7 +28,6 @@ provider "forgejo" {
 data "forgejo_user" "this" {
   login = "achim"
 }
-
 output "debug" {
   value = data.forgejo_user.this
 }

docs/index.md

@@ -16,7 +16,7 @@ Terraform provider for Forgejo — self-hosted lightweight software forge
 terraform {
   required_providers {
     forgejo = {
-      source = "registry.terraform.io/svalabs/forgejo"
+      source = "svalabs/forgejo"
     }
   }
 }
@@ -27,18 +27,16 @@ provider "forgejo" {
   username = "achim"
   password = "password"
 }
+data "forgejo_organization" "username" {
+  provider = forgejo.username
+  name     = "test1"
+}
 
 provider "forgejo" {
   alias     = "apiToken"
   host      = "http://localhost:3000"
   api_token = "c754bf42c0728e3031e8245a70dbdda0419aff44"
 }
-
-data "forgejo_organization" "username" {
-  provider = forgejo.username
-  name     = "test1"
-}
-
 data "forgejo_organization" "apiToken" {
   provider = forgejo.apiToken
   name     = "test1"