From 5e1e8bb9eced3c813e788d27168617f99dc3e8c0 Mon Sep 17 00:00:00 2001
From: hestiahacker <116128976+hestiahacker@users.noreply.github.com>
Date: Tue, 2 Jan 2024 04:56:44 -0600
Subject: [PATCH] docs: New developer getting started guide (#888)

* docs: Updated docs (removed broken commands, etc.) and added a script to get a bleeding edge version of golang #704

* docs: Added a guide to help developers who are new to this project

---------

Co-authored-by: hestia <hestia@hax0rbana.org>
---
 docs/guides/developer.md    | 75 +++++++++++++++++++++++++++++++++++++
 docs/guides/installation.md | 35 +++++++++--------
 go.yml                      | 17 +++++++++
 3 files changed, 111 insertions(+), 16 deletions(-)
 create mode 100644 docs/guides/developer.md
 create mode 100644 go.yml

diff --git a/docs/guides/developer.md b/docs/guides/developer.md
new file mode 100644
index 00000000..e36d2995
--- /dev/null
+++ b/docs/guides/developer.md
@@ -0,0 +1,75 @@
+# Overview
+This guide aims to help developers who are new to this project so more people
+can help investigate any problems they may run into.
+
+# Compilation
+Instructions on how to compile the provider, and cause terraform to use that
+newly compiled executable, see the
+[installation guide](https://github.com/Telmate/terraform-provider-proxmox/blob/new_developer_setup/docs/guides/installation.md#compile-the-executables-with-go).
+
+You may want to specify the namespace and specific path to the plugin to make
+sure terraform is getting the correct executable. If you are using the default
+example domain as your namespace, it'd look like this:
+
+```
+terraform {
+  required_providers {
+    proxmox = {
+      source = "registry.example.com/telmate/proxmox"
+      #source = "Telmate/proxmox"
+      version = ">=1.0.0"
+    }
+  }
+  required_version = ">= 0.14"
+}
+```
+
+After changing that, you'll need to update and upgrade your terraform files:
+
+```
+terraform get -update
+terraform init -upgrade
+```
+
+And finally, you'll want to check to make sure you only see the v1.0.0 entry
+when you look at the providers that terraform reports about.
+
+```
+terraform version
+```
+
+If you are going to be copying different executables into that same location
+repeatedly, you'll need to know that the hash of the executable is stored in
+.terraform.lock.hcl. You will have to either manually remove the block for your
+provisioner or just remove the file entirely before running the usual
+terraform get/init commands listed above.
+
+# Debugging
+Instructions on how to enable debug logging are located
+[here](https://registry.terraform.io/providers/Telmate/proxmox/latest/docs#pm_log_enable).
+
+# Going deeper
+Much of the code for the provider is not actually in this repo. It's in a
+library repo called proxmox-api-go. When you build the provider, the build
+system will check out a specific commit of that repo to get the code.
+
+This is controlled by [go.sum](https://github.com/Telmate/terraform-provider-proxmox/blob/master/go.sum#L5-L6)
+
+The convention seems to be `Version-Date-CommitHash`. As an example, the
+following was commit `31826f2fdc39` that was checked in on 2023-12-07:
+
+```
+github.com/Telmate/proxmox-api-go v0.0.0-20231207182448-31826f2fdc39 h1:0MvktdAFWIcc9F4IwQls2Em1F9z2LUZR1fSVm1PkKfM=
+github.com/Telmate/proxmox-api-go v0.0.0-20231207182448-31826f2fdc39/go.mod h1:xOwyTd8uC2IiYfmjwCVU2fTTVToFCm9yxJzn4cd7rPw=
+```
+
+If you want to make changes to the library (e.g. to add debug print
+statements), you'll need to change those lines in go.sum.
+
+Until someone figures out how to point this to a local directory and
+documents that here, this means pointing to your own fork of the proxmox-api-go
+and updating the version/date/hash yourself.
+
+If there is a way to get GoLang to fill update go.sum instead of having
+developers do it manually, please document that here or point to the official
+GoLang documentation on the topic.
diff --git a/docs/guides/installation.md b/docs/guides/installation.md
index 0d6064e1..977ae5ef 100644
--- a/docs/guides/installation.md
+++ b/docs/guides/installation.md
@@ -37,31 +37,24 @@ executables that have to be placed in the plugin directory.
 
 ## Compile the executables with Go
 
-In order to build the required executables, [install Go](https://golang.org/doc/install) first. Then clone this
-repository and run the following commands inside the cloned repository.
+First, clone this repo and cd into the repo's root.
 
 ```shell
-$ export GO111MODULE=on
-$ go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmox
+git clone https://github.com/Telmate/terraform-provider-proxmox
+cd terraform-provider-proxmox
 ```
 
-Then create the executables. They are placed in the `bin` folder inside the repository.
+In order to build the required executables, [install Go](https://golang.org/doc/install) first. If
+you want an automated way to do it, look at go.yml in the root of this repo.
 
-```shell
-$ cd terraform-provider-proxmox
-$ make
-```
-
-## Copy executables to plugin directory (Terraform <0.13)
-
-You need to copy these executables to the ~/.terraform.d directory which will also need to have a `plugins` directory
-created.
+Then to compile the provider:
 
 ```shell
-$ mkdir -p ~/.terraform.d/plugins
-$ cp -f bin/terraform-provider-proxmox_v2.0.0 ~/.terraform.d/plugins
+make
 ```
 
+The executable will be in the `./bin` directory.
+
 ## Copy executables to plugin directory (Terraform >=0.13)
 
 As of Terraform v0.13, locally-installed, third-party plugins
@@ -111,6 +104,16 @@ terraform {
 [...]
 ```
 
+## Copy executables to plugin directory (Terraform <0.13)
+
+You need to copy these executables to the ~/.terraform.d directory which will also need to have a `plugins` directory
+created.
+
+```shell
+mkdir -p ~/.terraform.d/plugins
+cp -f bin/terraform-provider-proxmox ~/.terraform.d/plugins
+```
+
 ## Initialize Terraform
 
 Initialize Terraform so that it installs the new plugins:
diff --git a/go.yml b/go.yml
new file mode 100644
index 00000000..35f766bd
--- /dev/null
+++ b/go.yml
@@ -0,0 +1,17 @@
+###
+# This is an ansible playbook that will install the bleeding edge version of
+# golang. This is needed because this project requires a newer version of go
+# than is available in any stable Debian release.
+#
+# To run this playbook:
+#   sudo apt install -y ansible
+#   ansible-galaxy install gantsign.ansible-role-golang
+#   ansible-playbook go.yml
+#
+# Then either restart your shell, or run `. /etc/profile.d/golang.sh` to
+# update your $PATH and you should be able to compile the provider with `make`
+###
+- name: Install and configure Golang
+  hosts: localhost
+  roles:
+    - role: gantsign.ansible-role-golang