v2: secure-by-default loader + discoverability, quality & project-health overhaul

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: Bug report
+description: Report a problem with the dotenv package
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A minimal .env snippet and Go code that reproduces the issue.
+      render: go
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: v2.0.0
+    validations:
+      required: true
+  - type: input
+    id: goversion
+    attributes:
+      label: Go version (go version)
+      placeholder: go1.23.0 linux/amd64
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/jaavier/dotenv/discussions
+    about: Ask questions and discuss usage with the community.
+  - name: Security vulnerability
+    url: https://github.com/jaavier/dotenv/security/advisories/new
+    about: Privately report a security issue (do not open a public issue).

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest an idea for the dotenv package
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem would this feature solve? Why do you need it?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the API or behavior you'd like.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!-- Thanks for contributing! Please fill out the sections below. -->
+
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that changes existing behavior)
+- [ ] Documentation only
+
+## Checklist
+
+- [ ] `go test ./...` passes
+- [ ] `gofmt -l .` reports no files
+- [ ] `golangci-lint run` is clean
+- [ ] Added/updated tests for the change
+- [ ] Updated documentation (README / doc comments) if needed

.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "build"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (go ${{ matrix.go }} / ${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        go: ["1.17", "1.20", "1.22", "1.23"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - run: go build ./...
+      - run: go vet ./...
+      - run: go test ./...
+
+  race:
+    name: race + coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+          cache: true
+      - run: go test -race -covermode=atomic -coverprofile=coverage.out ./...
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.out
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+          cache: true
+      - name: gofmt
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "These files are not gofmt-ed:"; echo "$unformatted"; exit 1
+          fi
+      - uses: golangci/golangci-lint-action@v6
+        with:
+          version: v2.5.0

.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (Go)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: go
+          queries: security-and-quality
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.golangci.yml

@@ -0,0 +1,24 @@
+version: "2"
+
+linters:
+  enable:
+    - misspell
+    - unconvert
+    - revive
+  settings:
+    misspell:
+      locale: US
+  exclusions:
+    rules:
+      # Setting/unsetting env vars and cleanup in tests/examples is best-effort.
+      - path: (_test\.go|example/program\.go)
+        linters:
+          - errcheck
+      # QF1001 (apply De Morgan's law) is a style quickfix, not a correctness issue.
+      - text: "QF1001"
+        linters:
+          - staticcheck
+
+formatters:
+  enable:
+    - gofmt

CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - Unreleased
+
+This is a major release. The module path is now
+`github.com/jaavier/dotenv/v2` — update your imports accordingly:
+
+```go
+import "github.com/jaavier/dotenv/v2"
+```
+
+### Added
+
+- `Parse(io.Reader)` and `ParseBytes([]byte)` — pure parsing into a
+  `map[string]string` with **no** side effects on the process environment.
+- `Overload(...)` — explicit loader that lets file values override existing
+  environment variables.
+- `Options.MaxFileSize` and the `DefaultMaxFileSize` constant to configure the
+  size limit.
+- `ErrFileTooLarge` sentinel error (testable via `errors.Is`).
+- Support for multi-line quoted values (e.g. PEM keys), the optional leading
+  `export` token, UTF-8 BOM, and CRLF line endings.
+- Testable examples (rendered on pkg.go.dev) and benchmarks.
+
+### Changed
+
+- **BREAKING (module path):** the module is now `github.com/jaavier/dotenv/v2`.
+- **BREAKING (security default):** `Load` and `LoadWithOptions(nil, ...)` no
+  longer override variables that already exist in the process environment.
+  Following the 12-factor methodology, the real environment is authoritative
+  and a `.env` file only fills in what is missing. Use `Overload` (or
+  `Options{Override: true}`) for the previous override behavior.
+- Files are now applied **atomically**: the whole file is parsed before any
+  variable is set, so a malformed file never leaves a half-applied environment.
+- Correct POSIX-ish quoting: double quotes expand escapes (`\n \r \t \\ \"`),
+  single quotes are literal, and unquoted values support inline `# comments`.
+- The size limit is enforced on the bytes actually read (safe for pipes and
+  special files), and the 64 KB line cap from `bufio.Scanner` is gone.
+
+### Fixed
+
+- Single-quoted and unquoted values no longer have escape sequences expanded.
+- Trailing garbage after a closing quote is now rejected as `ErrInvalidFormat`.
+
+## [1.1.0] - Earlier release
+
+- Clean-architecture refactor and utility functions (`Get`, `GetOrDefault`,
+  `GetOrPanic`, `MustLoad`).
+
+## [1.0.0] - Initial release
+
+- Initial `.env` loader with `Load` / `LoadWithOptions`.
+
+[2.0.0]: https://github.com/jaavier/dotenv/compare/v1.1.0...v2.0.0
+[1.1.0]: https://github.com/jaavier/dotenv/releases/tag/v1.1.0
+[1.0.0]: https://github.com/jaavier/dotenv/releases/tag/v1.0.0

CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Contributor Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the community.
+
+Unacceptable behavior includes harassment, insulting or derogatory comments,
+and personal or political attacks.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers. All complaints will be reviewed and investigated
+promptly and fairly.
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for your interest in improving `dotenv`! This package aims to stay
+**small, dependency-free, and secure**, so contributions are evaluated with
+that philosophy in mind.
+
+## Getting started
+
+```bash
+git clone https://github.com/jaavier/dotenv
+cd dotenv
+make test      # run the test suite
+make race      # run with the race detector
+make cover     # coverage report
+make lint      # golangci-lint
+```
+
+If you don't have `make`, the equivalent commands are:
+
+```bash
+go test ./...
+go test -race ./...
+golangci-lint run ./...
+gofmt -l .     # should print nothing
+```
+
+## Guidelines
+
+- **Keep it minimal.** No third-party dependencies. The package should remain a
+  single, focused file.
+- **Tests first.** New behavior needs tests; bug fixes should come with a
+  regression test.
+- **Security by default.** Changes must not weaken the safe defaults (e.g. not
+  overriding existing environment variables).
+- **Formatting & linting.** `gofmt -l .` must be empty and `golangci-lint run`
+  must be clean before you open a PR.
+- **Document it.** Update doc comments and the README when behavior changes, and
+  add an entry to `CHANGELOG.md`.
+
+## Pull requests
+
+1. Fork and create a feature branch.
+2. Make your change with tests and docs.
+3. Ensure CI is green.
+4. Open a PR using the template and describe the motivation clearly.
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).