v2: secure-by-default loader + discoverability, quality & project-health overhaul#3
Merged
Conversation
Redesign the loader to be lighter and security-first while keeping the public API backward compatible (existing tests still pass). Security & correctness: - Default no longer overrides existing env vars (12-factor): the process environment is authoritative. Add Overload / Options.Override for opt-in. - Files are applied atomically: parse fully before setting any variable, so a malformed file never leaves a half-applied environment. - POSIX-ish quoting fixed: double quotes expand escapes (\n \r \t \\ \"), single quotes are literal, unquoted values support inline "# comments". - Reject trailing garbage after a closing quote (ErrInvalidFormat). - Support optional leading "export " token and UTF-8 BOM. - Multi-line quoted values (e.g. PEM keys) are supported. - Replace bufio.Scanner (64KB line cap) with byte-based parsing. - Enforce size limit on bytes actually read (safe for pipes/special files); add configurable Options.MaxFileSize and ErrFileTooLarge sentinel. New API (additive, zero dependencies, single file): - Parse(io.Reader) / ParseBytes([]byte): pure parsing into a map with no global side effects. - Overload(...): explicit override loader. - DefaultMaxFileSize constant. Docs & tests: - Rewrite README (EN/ES) for the new behavior; drop the misleading "path sanitization prevents directory traversal" claim. - Update example to showcase Parse and Overload. - Add parse_test.go covering quoting, comments, export, BOM/CRLF, multi-line, override semantics, atomicity, size limits, and no-side-effect parsing. https://claude.ai/code/session_01P1nZkYKTFp9CRKDUEysphw
Add the infrastructure and documentation that drive a Go package's discoverability on pkg.go.dev, Go Report Card and search engines. Discoverability & docs: - README: pkg.go.dev / Go Report Card / CI / codecov / license / version / zero-deps badges, keyword-rich tagline, a "Why dotenv? (vs godotenv)" comparison table, performance numbers, and an FAQ targeting common queries. - Keyword-optimized package synopsis (the first sentence pkg.go.dev indexes). - Testable Example functions (rendered on pkg.go.dev) and benchmarks. Quality & trust signals: - GitHub Actions CI: build/vet/test matrix across Go 1.17–1.23 on Linux/macOS/Windows, a race+coverage job (Codecov), and a gofmt+golangci-lint job. - CodeQL security scanning workflow. - golangci-lint v2 config; repo is lint-clean and gofmt-clean (incl. existing test file). - Dependabot for modules and GitHub Actions. Project health: - CHANGELOG, CONTRIBUTING, SECURITY (private advisory reporting + design notes), CODE_OF_CONDUCT, issue forms, PR template, and a Makefile. Coverage is 90%; all examples and benchmarks pass. https://claude.ai/code/session_01P1nZkYKTFp9CRKDUEysphw
The secure-by-default behavior change (Load no longer overrides existing environment variables) is a breaking change, so the module is promoted to major version 2 per semantic import versioning. - go.mod module path -> github.com/jaavier/dotenv/v2 - Update all imports (examples, tests) and doc comment - README: install/import snippets and pkg.go.dev / Go Report Card badges -> /v2, add a "How do I upgrade from v1?" FAQ entry - CHANGELOG: frame as 2.0.0 with BREAKING notes (module path + security default) - SECURITY: mark 2.x as supported BREAKING CHANGE: import path is now github.com/jaavier/dotenv/v2 and Load no longer overrides pre-existing environment variables (use Overload to opt in). https://claude.ai/code/session_01P1nZkYKTFp9CRKDUEysphw
Review or Edit in CodeSandboxOpen the branch in Web Editor • VS Code • Insiders |
|
You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool. What Enabling Code Scanning Means:
For more information about GitHub Code Scanning, check out the documentation. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
dotenvlighter, safer, and far more discoverable, released as a v2 module (github.com/jaavier/dotenv/v2).This PR has three parts:
1. Secure-by-default loader (code)
Loadno longer overrides variables already present in the process environment (12-factor). Use the newOverload/Options.Overrideto opt in.\n \r \t \\ \"), single quotes are literal, unquoted values support inline# comments, optional leadingexport, UTF-8 BOM and CRLF.bufio.Scanner64 KB line cap.Options.MaxFileSize+ErrFileTooLarge.Parse(io.Reader)/ParseBytes([]byte)(pure, no global side effects),Overload(...),DefaultMaxFileSize.2. Discoverability (pkg.go.dev / Go Report Card / search)
3. Quality & project health
Verification
go build,go vet,golangci-lint run— all clean (0 issues)go test -racepasses; coverage 90%gofmt -l .empty; all CI YAML validatedBreaking changes
github.com/jaavier/dotenv/v2.Loadno longer overrides pre-existing environment variables (useOverload).Follow-up (manual, no API available)
After merge, to complete discoverability:
main(triggers Go proxy re-indexing).https://claude.ai/code/session_01P1nZkYKTFp9CRKDUEysphw
Generated by Claude Code