docs: New developer getting started guide

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.

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:

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