From cd723f5f14e156b6939094c2bb8947887d4ebf34 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Tue, 10 Sep 2024 14:38:10 -0400 Subject: [PATCH] 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. --- .github/workflows/ci.yaml | 3 ++- .github/workflows/coverage.yaml | 2 +- CONTRIBUTING.md | 18 +++++++++-------- Makefile | 2 +- README.md | 20 ++++++++++++++----- docs/Makefile | 28 ++++++++++++++++---------- docs/_quarto.yml | 4 ++-- integration/Makefile | 34 ++++++++++++++++++++------------ integration/compose.yaml | 4 ++-- vars.mk | 35 ++++++++------------------------- 10 files changed, 80 insertions(+), 70 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a89c6ba1..2cf10d30 100644 --- a/.github/workflows/ci.yaml +++ b/.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 }} diff --git a/.github/workflows/coverage.yaml b/.github/workflows/coverage.yaml index 7310e6fd..611494cd 100644 --- a/.github/workflows/coverage.yaml +++ b/.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 }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83498f97..5c290734 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/Makefile b/Makefile index 75015c50..96c54ab6 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 4c7c4704..dcbb1adc 100644 --- a/README.md +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index fdc04a79..ae4deb92 100644 --- a/docs/Makefile +++ b/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: diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 4983a130..a0555602 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -5,7 +5,7 @@ execute: freeze: auto website: - title: "Posit SDK {{< env VERSION >}}" + title: "Posit SDK {{< env PROJECT_VERSION >}}" bread-crumbs: true favicon: "_extensions/posit-dev/posit-docs/assets/images/favicon.svg" navbar: @@ -31,7 +31,7 @@ website: left: | Copyright © 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' diff --git a/integration/Makefile b/integration/Makefile index 0efd9a88..605a8944 100644 --- a/integration/Makefile +++ b/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: diff --git a/integration/compose.yaml b/integration/compose.yaml index 225f9a37..35bb6a81 100644 --- a/integration/compose.yaml +++ b/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} diff --git a/vars.mk b/vars.mk index 7907dafe..36cec07c 100644 --- a/vars.mk +++ b/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