chore: cleaning (#278)

- Update GitHub Action imports to the latest version.
- Update CONTRIBUTING.md to reflect the current development lifecycle.
- Update README.md usage instructions.
- Refactor `vars.mk`.
- Move non-global environment variables from `vars.mk` to their proper
locations.
- Update environment variable names across the stack to use proper
conventions.

Author: tdstein

.github/workflows/ci.yaml

@@ -70,7 +70,8 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: docker/setup-buildx-action@v3
-    - run: echo "$CONNECT_LICENSE" > ./integration/license.lic
+    - name: Write Posit Connect license to disk
+      run: echo "$CONNECT_LICENSE" > ./integration/license.lic
       env:
         CONNECT_LICENSE: ${{ secrets.CONNECT_LICENSE }}
     - run: make -C ./integration ${{ matrix.CONNECT_VERSION }}

.github/workflows/coverage.yaml

@@ -21,7 +21,7 @@ jobs:
       - run: make test
       - run: make cov-xml
       - if: ${{ ! github.event.pull_request.head.repo.fork }}
-        uses: orgoro/coverage@v3.1
+        uses: orgoro/coverage@v3.2
         with:
             coverageFile: coverage.xml
             token: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -10,20 +10,22 @@ Before contributing to the `posit-sdk`, ensure that the following prerequisites
 
 - Python >=3.8
 
-> [!TIP]
-> We recommend using virtual environments to maintain a clean and consistent development environment.
+> [!INFO]
+> We require using virtual environments to maintain a clean and consistent development environment.
+> Any Python virtual environment will do.
 
 ## Instructions
 
 > [!WARNING]
-> Executing `make` will utilize `pip` to install third-party packages in your activated Python environment. Please review the [`Makefile`](./Makefile) to verify behavior before executing any commands.
+> Executing `make` will install third-party packages in your Python environment. Please review the [`Makefile`](./Makefile) to verify behavior before executing any commands.
 
 1. Fork the repository and open it in your development environment.
-2. Run `make` to run the default development workflow.
-3. Make your changes and test them thoroughly using `make test`
-4. Run `make fmt` and `make lint` to verify adherence to the project style guide.
-5. Commit your changes and push them to your forked repository.
-6. Submit a pull request to the main repository.
+2. Activate your Python environment (e.g., `source .venv/bin/activate`)
+3. Run `make` to run the default development workflow.
+4. Make your changes and test them thoroughly using `make test`
+5. Run `make fmt` and `make lint` to verify adherence to the project style guide.
+6. Commit your changes and push them to your forked repository.
+7. Submit a pull request to the main repository.
 
 ## Tooling
 

Makefile

@@ -61,7 +61,7 @@ test:
 	$(PYTHON) -m coverage run --source=src -m pytest tests
 
 uninstall: ensure-uv
-	$(UV) pip uninstall $(NAME)
+	$(UV) pip uninstall $(PROJECT_NAME)
 
 version:
 	@$(PYTHON) -m setuptools_scm

README.md

@@ -12,7 +12,7 @@ pip install posit-sdk
 
 ## Usage
 
-Establish server information and credentials using the following environment variables or when initializing a client. Then checkout some [examples](./examples/0001-overview.qmd) to get started.
+Establish server information and credentials using the following environment variables or when initializing a client. Then checkout the [Posit Connect Cookbook](https://docs.posit.co/connect/cookbook/) to get started.
 
 > [!CAUTION]
 > It is important to keep your API key safe and secure. Your API key grants access to your account and allows you to make authenticated requests to the Posit API. Treat your API key like a password and avoid sharing it with others. If you suspect that your API key has been compromised, regenerate a new one immediately to maintain the security of your account.
@@ -27,17 +27,27 @@ export CONNECT_SERVER="https://example.com/"
 ```python
 from posit.connect import Client
 
-with Client() as client:
-    print(client)
+client = Client()
 ```
 
 ### Option 2
 
+```shell
+export CONNECT_API_KEY="my-secret-api-key"
+```
+
+```python
+from posit.connect import Client
+
+Client("https://example.com")
+```
+
+### Option 3
+
 ```python
 from posit.connect import Client
 
-with Client(api_key="my-secret-api-key", url="https://example.com") as client:
-    print(client)
+Client("https://example.com", "my-secret-api-key")
 ```
 
 ## Contributing

docs/Makefile

@@ -1,26 +1,34 @@
 include ../vars.mk
 
-VERSION := $(shell $(MAKE) -C ../ -s version)
+# Site settings
+PROJECT_VERSION ?= $(shell $(MAKE) -C ../ -s version)
+CURRENT_YEAR ?= $(shell date +%Y)
+
+# Quarto settings
+QUARTO ?= quarto
+QUARTODOC ?= quartodoc
+
+# Netlify settings
+NETLIFY_SITE_ID ?= 5cea1f56-7935-4387-975a-18a7905d15ee
+NETLIFY_ARGS :=
+ifeq ($(ENV), prod)
+    NETLIFY_ARGS = --prod
+endif
 
 .DEFAULT_GOAL := all
 
-.PHONY: all \
-		api \
-		build \
-		clean \
-		deps \
-		preview
+.PHONY: all api build clean deps preview deploy
 
 all: deps api build
 
 api:
 	$(QUARTODOC) build
 	$(QUARTODOC) interlinks
-	cp -r _extensions/ reference/_extensions	# Required to render footer
+	cp -r _extensions/ reference/_extensions  # Required to render footer
 
 build:
 	CURRENT_YEAR=$(CURRENT_YEAR) \
-	VERSION=$(VERSION) \
+	PROJECT_VERSION=$(PROJECT_VERSION) \
 	$(QUARTO) render
 
 clean:
@@ -34,7 +42,7 @@ deps:
 
 preview:
 	CURRENT_YEAR=$(CURRENT_YEAR) \
-	VERSION=$(VERSION) \
+	PROJECT_VERSION=$(PROJECT_VERSION) \
 	$(QUARTO) preview
 
 deploy:

docs/_quarto.yml

@@ -5,7 +5,7 @@ execute:
   freeze: auto
 
 website:
-  title: "Posit SDK <small>{{< env VERSION >}}</small>"
+  title: "Posit SDK <small>{{< env PROJECT_VERSION >}}</small>"
   bread-crumbs: true
   favicon: "_extensions/posit-dev/posit-docs/assets/images/favicon.svg"
   navbar:
@@ -31,7 +31,7 @@ website:
     left: |
       Copyright &copy; 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved.
     center: |
-      Posit PRODUCT {{< env VERSION >}}
+      Posit {{< env PROJECT_VERSION >}}
     right:
       - icon: question-circle-fill
         aria-label: 'Link to Posit Support'

integration/Makefile

@@ -1,5 +1,13 @@
 include ../vars.mk
 
+# Docker settings
+DOCKER_COMPOSE ?= docker compose
+DOCKER_CONNECT_IMAGE ?= rstudio/rstudio-connect
+DOCKER_PROJECT_IMAGE_TAG ?= $(PROJECT_NAME):latest
+
+# Connect settings
+CONNECT_BOOTSTRAP_SECRETKEY ?= $(shell head -c 32 /dev/random | base64)
+
 .DEFAULT_GOAL := all
 
 .PHONY: $(CONNECT_VERSIONS) \
@@ -57,13 +65,13 @@ latest:
 # Run test suite against preview Connect version.
 preview:
 	$(MAKE) \
-	CONNECT_IMAGE=rstudio/rstudio-connect-preview \
-	CONNECT_IMAGE_TAG=dev-jammy-daily \
+	DOCKER_CONNECT_IMAGE=rstudio/rstudio-connect-preview \
+	DOCKER_CONNECT_IMAGE_TAG=dev-jammy-daily \
 	down-preview up-preview
 
 # Build Dockerfile
 build:
-	docker build -t $(IMAGE_TAG) ..
+	docker build -t $(DOCKER_PROJECT_IMAGE_TAG) ..
 
 # Tear down resources.
 #
@@ -74,15 +82,15 @@ build:
 #   make down
 #   make down-2024.05.0
 down: $(CONNECT_VERSIONS:%=down-%)
-down-%: CONNECT_IMAGE_TAG=jammy-$*
+down-%: DOCKER_CONNECT_IMAGE_TAG=jammy-$*
 down-%: CONNECT_VERSION=$*
 down-%:
 	CONNECT_BOOTSTRAP_SECRETKEY=$(CONNECT_BOOTSTRAP_SECRETKEY) \
-	CONNECT_IMAGE=$(CONNECT_IMAGE) \
-	CONNECT_IMAGE_TAG=$(CONNECT_IMAGE_TAG) \
+	DOCKER_CONNECT_IMAGE=$(DOCKER_CONNECT_IMAGE) \
+	DOCKER_CONNECT_IMAGE_TAG=$(DOCKER_CONNECT_IMAGE_TAG) \
 	CONNECT_VERSION=$* \
-	IMAGE_TAG=$(IMAGE_TAG) \
-	$(DOCKER_COMPOSE) -p $(NAME)-$(subst .,-,$(CONNECT_VERSION)) down -v
+	DOCKER_PROJECT_IMAGE_TAG=$(DOCKER_PROJECT_IMAGE_TAG) \
+	$(DOCKER_COMPOSE) -p $(PROJECT_NAME)-$(subst .,-,$(CONNECT_VERSION)) down -v
 
 # Create, start, and run Docker Compose.
 #
@@ -92,14 +100,14 @@ down-%:
 #   make up-2024.05.0
 up: $(CONNECT_VERSIONS:%=up-%)
 up-%: CONNECT_VERSION=$*
-up-%: CONNECT_IMAGE_TAG=jammy-$*
+up-%: DOCKER_CONNECT_IMAGE_TAG=jammy-$*
 up-%: build
 	CONNECT_BOOTSTRAP_SECRETKEY=$(CONNECT_BOOTSTRAP_SECRETKEY) \
-	CONNECT_IMAGE=$(CONNECT_IMAGE) \
-	CONNECT_IMAGE_TAG=$(CONNECT_IMAGE_TAG) \
+	DOCKER_CONNECT_IMAGE=$(DOCKER_CONNECT_IMAGE) \
+	DOCKER_CONNECT_IMAGE_TAG=$(DOCKER_CONNECT_IMAGE_TAG) \
 	CONNECT_VERSION=$* \
-	IMAGE_TAG=$(IMAGE_TAG) \
-	$(DOCKER_COMPOSE) -p $(NAME)-$(subst .,-,$(CONNECT_VERSION)) up -V --abort-on-container-exit --no-build
+	DOCKER_PROJECT_IMAGE_TAG=$(DOCKER_PROJECT_IMAGE_TAG) \
+	$(DOCKER_COMPOSE) -p $(PROJECT_NAME)-$(subst .,-,$(CONNECT_VERSION)) up -V --abort-on-container-exit --no-build
 
 # Show help message.
 help:

integration/compose.yaml

@@ -1,6 +1,6 @@
 services:
   tests:
-    image: ${IMAGE_TAG}
+    image: ${DOCKER_PROJECT_IMAGE_TAG}
     # Run integration test suite.
     #
     # Target is relative to the ./integration directory, not the project root
@@ -20,7 +20,7 @@ services:
     networks:
       - test
   connect:
-    image: ${CONNECT_IMAGE}:${CONNECT_IMAGE_TAG}
+    image: ${DOCKER_CONNECT_IMAGE}:${DOCKER_CONNECT_IMAGE_TAG}
     environment:
       - CONNECT_BOOTSTRAP_ENABLED=true
       - CONNECT_BOOTSTRAP_SECRETKEY=${CONNECT_BOOTSTRAP_SECRETKEY}

vars.mk

@@ -6,34 +6,15 @@
 # - ./docs/Makefile
 # - ./integration/Makefile
 
-CONNECT_BOOTSTRAP_SECRETKEY ?= $(shell head -c 32 /dev/random | base64)
-
-CONNECT_IMAGE ?= rstudio/rstudio-connect
-
-CURRENT_YEAR ?= $(shell date +%Y)
-
-DOCKER_COMPOSE ?= docker compose
+# Shell settings
+SHELL := /bin/bash
 
+# Environment settings
 ENV ?= dev
 
-IMAGE_TAG ?= $(NAME):latest
-
-NAME := posit-sdk
-
-ifeq ($(ENV), prod)
-    NETLIFY_ARGS := --prod
-else
-    NETLIFY_ARGS :=
-endif
-
-NETLIFY_SITE_ID ?= 5cea1f56-7935-4387-975a-18a7905d15ee
-
-PYTHON := $(shell command -v python || command -v python3)
-
-QUARTO ?= quarto
-
-QUARTODOC ?= quartodoc
-
-SHELL := /bin/bash
+# Project settings
+PROJECT_NAME := posit-sdk
 
-UV := uv
+# Python settings
+PYTHON ?= $(shell command -v python || command -v python3)
+UV ?= uv