Skip to content

Commit be217cd

Browse files
ian-floresian-flores
committed
feat: add project configuration files
Add CLAUDE.md, CONTRIBUTING.md, and PR template. Updated CLAUDE.md to reflect public repo structure.
1 parent bd44f3b commit be217cd

File tree

3 files changed

+164
-0
lines changed

3 files changed

+164
-0
lines changed

‎.github/pull_request_template.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Description
2+
3+
<!--
4+
Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies required for this change.
5+
6+
## Issue
7+
8+
Link to GitHub or JIRA issue tracking this work; if it exists.
9+
-->
10+
11+
## Category of change
12+
13+
- [ ] Site config change (adjusting site.yaml or other config files)
14+
- [ ] Bug fix (non-breaking change which fixes an issue)
15+
- [ ] Version upgrade (upgrading the version of a service or product)
16+
- [ ] New feature (non-breaking change which adds functionality)
17+
- [ ] Build: a code change that affects the build system or external dependencies
18+
- [ ] Performance: a code change that improves performance
19+
- [ ] Refactor: a code change that neither fixes a bug nor adds a feature
20+
- [ ] Documentation: documentation changes
21+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
22+
- [ ] This change requires a documentation update
23+
24+
## Checklist
25+
26+
- [ ] I have tested in [`ganso01-staging`](https://ganso.lab.staging.posit.team/) and confirmed my change works
27+
- [ ] I have created a [Changelog Entry](https://positpbc.atlassian.net/wiki/spaces/PTD/database/1449394520?atlOrigin=eyJpIjoiYWJiZWUwYzEyYzY5NDlmYmEyMmZlYmEyYzVlYmZiZmQiLCJwIjoiYyJ9) for this PR

‎CLAUDE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Posit Team Dedicated (PTD)
2+
3+
## Project Structure
4+
5+
The project is organized into several key components:
6+
7+
- **`./cmd`**: Contains the main CLI tool (Go implementation)
8+
- **`./lib`**: Common Go libraries and utilities
9+
- **`./python-pulumi`**: Python package with Pulumi infrastructure-as-code resources
10+
- **`./examples`**: Example configurations for control rooms and workloads
11+
- **`./e2e`**: End-to-end tests
12+
- **`./docs`**: Documentation (see [docs/README.md](docs/README.md) for structure)
13+
- **`./docs/cli`**: CLI reference documentation
14+
- **`./docs/team-operator`**: Team Operator documentation
15+
- **`./docs/guides`**: How-to guides for common tasks
16+
- **`./docs/infrastructure`**: Infrastructure documentation
17+
- **`./Justfile`**: Command runner file with various tasks (`just -l` to list commands)
18+
19+
### Team Operator
20+
21+
The Team Operator is a Kubernetes operator that manages the deployment and configuration of Posit Team products within a Kubernetes cluster. It is maintained in a separate public repository: [posit-dev/team-operator](https://github.com/posit-dev/team-operator).
22+
23+
PTD consumes the Team Operator via its public Helm chart at `oci://ghcr.io/posit-dev/charts/team-operator`.
24+
25+
**Testing with adhoc images:** PR builds from posit-dev/team-operator publish adhoc images to GHCR. To test:
26+
```yaml
27+
# In ptd.yaml cluster spec
28+
adhoc_team_operator_image: "ghcr.io/posit-dev/team-operator:adhoc-{branch}-{version}"
29+
```
30+
31+
## CLI Configuration
32+
33+
The PTD CLI uses Viper for configuration management. Configuration can be set via:
34+
- **CLI flags**: Highest precedence (e.g., `--targets-config-dir`)
35+
- **Environment variables**: Second precedence (e.g., `PTD_TARGETS_CONFIG_DIR`)
36+
- **Config file**: Third precedence (`~/.config/ptd/ptdconfig.yaml`)
37+
- **Defaults**: Lowest precedence
38+
39+
### Targets Configuration Directory
40+
41+
PTD expects target configurations in a targets directory. Configure it via:
42+
43+
```yaml
44+
# ~/.config/ptd/ptdconfig.yaml
45+
targets_config_dir: /path/to/your/targets
46+
```
47+
48+
Or via environment variable:
49+
```bash
50+
export PTD_TARGETS_CONFIG_DIR=/path/to/your/targets
51+
```
52+
53+
Or via CLI flag:
54+
```bash
55+
ptd --targets-config-dir /path/to/your/targets ensure workload01
56+
```
57+
58+
The targets configuration directory must contain:
59+
- `__ctrl__/`: Control room configurations
60+
- `__work__/`: Workload configurations
61+
62+
See [examples/](examples/) for example configurations.
63+
64+
### Go→Python Integration
65+
66+
The Go CLI communicates the infrastructure path to Python Pulumi stacks via the `PTD_ROOT` environment variable:
67+
- **Go**: Sets `PTD_ROOT` in `lib/pulumi/python.go` when invoking Python
68+
- **Python**: Reads `PTD_ROOT` in `python-pulumi/src/ptd/paths.py`
69+
- **Tests**: Python tests must set `PTD_ROOT` via `monkeypatch.setenv()`
70+
71+
## Build and Development Commands
72+
73+
### Overall Project Commands (from root Justfile)
74+
75+
- `just deps`: Install dependencies
76+
- `just check`: Check all (includes linting and formatting)
77+
- `just test`: Test all
78+
- `just build`: Build all
79+
- `just format`: Run automatic formatting
80+
81+
#### Check Commands
82+
83+
- `just check-python-pulumi`: Check Python Pulumi code
84+
85+
#### Build Commands
86+
87+
- `just build-cmd`: Build command-line tool
88+
89+
#### Test Commands
90+
91+
- `just test-cmd`: Test command-line tool
92+
- `just test-e2e`: Run end-to-end tests (requires URL argument)
93+
- `just test-lib`: Test library code
94+
- `just test-python-pulumi`: Test Python Pulumi code
95+
96+
#### AWS Development
97+
98+
- `just aws-unset`: Unset all AWS environment variables
99+
- `just latest-images`: Show latest ECR images
100+
101+
## Contributing
102+
103+
When contributing to the project:
104+
105+
1. Ensure that Snyk tests pass before merging a PR
106+
2. Follow the development workflows described in the repository files
107+
3. Use the provided Justfiles for common tasks
108+
4. Always run `just format` before committing changes to ensure code style consistency
109+
110+
# Additional Instructions
111+
- LLM coding instructions shared with copilot: [.github/copilot/copilot-instructions.md](.github/copilot/copilot-instructions.md)
112+
- Follow the template in [.github/pull_request_template.md](.github/pull_request_template.md) to format PR descriptions correctly

‎CONTRIBUTING.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Contributing
2+
3+
Below are some helpful directions on getting your environment set up as well as contributing guidelines.
4+
5+
Tooling:
6+
- `snyk` CLI
7+
- local installation of `rskey`
8+
- local installation of `kustomize`
9+
- local installation of `pulumi` and `python3`
10+
- local installation of `golang`
11+
12+
## Setting up `snyk`
13+
14+
It is helpful to be able to run `snyk` locally for development (particularly if a PR fails the `snyk` test).
15+
16+
> Our expectation is that `snyk` would be passing before merging a given PR
17+
18+
1. Install the `snyk` CLI. On Mac systems, you can run `brew install snyk-cli`
19+
20+
2. Run `snyk auth`. This authenticates your local CLI with your SSO
21+
credentials. We also have a `just snyk-auth` for this as well.
22+
23+
3. Run `snyk monitor --org=posit-team-dedicated --all-projects
24+
--policy-path=.snyk` from the root directory. We also have a `just snyk`
25+
target to do this for you.

0 commit comments

Comments
 (0)