Skip to content

Add Developer Experience Audit Report #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Snider wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add Developer Experience Audit Report #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AUDIT-DX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Developer Experience (DX) Audit

This document evaluates the developer experience for contributors to the Poindexter project.

## Onboarding

| Category | Rating | Notes |
|---|---|---|
| **Time to First Build** | ✅ Excellent | `make build` completed in ~23 seconds. No external dependencies to install, making the initial setup very fast. |
| **Dependencies** | ✅ Excellent | The project has no external Go module dependencies, which significantly simplifies the setup process. However, `golangci-lint` is required for the full CI process and is not automatically installed. |
| **Documentation** | ✅ Good | The `README.md` and `CONTRIBUTING.md` files are clear, comprehensive, and provide a good overview of the project and its development process. |
| **Gotchas** | ⚠️ Fair | The `make lint` and `make ci` commands fail if `golangci-lint` is not installed. This is a significant gotcha that can block a new contributor. The `CONTRIBUTING.md` mentions this, but it could be made more prominent or automated. Additionally, running a single test file with `go test <file>` fails, which could be confusing. |

## Development Workflow

| Category | Rating | Notes |
|---|---|---|
| **Local Development** | ✅ Good | The fast build and test times provide a tight feedback loop. There is no hot-reloading, but this is not expected for a Go library. |
| **Testing** | ✅ Good | `make test` completes in ~7 seconds. Running a single test is easy with `go test -run <TestName>`, which is the idiomatic Go approach. The test output is clear and concise. |
| **Build System** | ✅ Good | The `Makefile` is well-structured and the commands are intuitive. The build system does not appear to support incremental builds, but this is not a major issue for a project of this size. |
| **Tooling** | ⚠️ Fair | `golangci-lint` is used for linting, but its installation is not automated. There are no editor configurations provided. Formatting is handled by `go fmt`. Type checking is handled by the Go compiler. |
| **CLI/Interface** | N/A | The project is a library and does not have a CLI. |

## Pain Points

* **`golangci-lint` Dependency:** The biggest pain point is the manual installation of `golangci-lint`. This can be a significant hurdle for new contributors and disrupts the development workflow.
* **Single Test Execution:** The failure of `go test <file>` is a minor pain point that could be confusing for developers who are not familiar with the idiomatic `go test -run <TestName>` command.

## Suggestions for Improvement

* **Automate `golangci-lint` Installation:** The `Makefile` could be updated to automatically install `golangci-lint` if it's not already present. This would significantly improve the onboarding experience.
* **Document Single Test Execution:** The `CONTRIBUTING.md` file could be updated to explicitly mention that single tests should be run with `go test -run <TestName>`.
* **Provide Editor Configurations:** Adding `.editorconfig`, `.vscode`, or `.idea` files would help ensure consistent formatting and coding style across different editors.
Loading