Repository Trust

GitHub documents repository customization through official pages such as About READMEs, Licensing a repository, and Ignoring files. Use those pages for current product behavior, but teach the underlying model: a repository should explain purpose, permissions, local setup, safe configuration, contribution expectations, and current maintenance status.

README As The Front Door

A README is not a dumping ground for every idea about the project. It is the front door. A good README answers the questions a visitor asks before committing time: what is this, who is it for, what problem does it solve, how do I run it, how do I test it, what state is it in, where is the documentation, and how should I report problems?

For a small PHP project, the README should usually include a concise description, requirements, installation steps, configuration steps, database setup if any, test command, development server command, deployment notes if the repository owns deployment, and a status statement. If the project is a package, include installation through Composer, supported PHP versions, a minimal usage example, and compatibility promises. If the project is an application, include environment variables through .env.example, not real credentials.

Bad READMEs often fail by being either too vague or too noisy. This is my PHP app teaches nothing. A wall of badges, screenshots, and marketing claims without setup instructions is also unhelpful. The best README is written for the next person who must make a decision: clone it, run it, review it, contribute to it, deploy it, or decide not to use it.

Badges Are Claims

Badges can be useful when they summarize live status: CI passing, latest release, package version, license, coverage, static-analysis level, supported PHP version, or documentation status. They are harmful when they become decoration or lie by omission. A green build badge does not prove security. A coverage badge does not prove meaningful tests. A license badge must match the actual license file.

Treat each badge as a claim that must be backed by an authoritative source. A CI badge should link to the workflow. A package badge should link to the package registry. A license badge should match the repository license. If a badge is broken, stale, or unrelated, remove it. Trust is better served by fewer accurate signals than by a row of impressive-looking images.

License Is Not Optional For Reuse

A public repository without a license can be viewed, but visitors do not automatically receive clear permission to reuse, modify, or distribute the code. That matters for open source, examples, snippets, and package publishing. GitHub's license documentation explains how to add a license, but the curriculum should teach the decision: what permissions are you granting, what obligations are you imposing, and are you allowed to license the code at all?

Common open-source licenses answer different questions. Permissive licenses generally allow broad reuse with attribution and warranty disclaimers. Copyleft licenses generally require derivative works to preserve similar freedoms under specified conditions. Some repositories should not be open source because they contain proprietary code, client work, unclear third-party ownership, or material the author is not allowed to license. In those cases, a public repository may still be a bad idea.

Do not invent a license by writing free to use in the README. Use a recognized license when reuse is intended, or explicitly state that the repository is not currently licensed for reuse. For a curriculum project, learners do not need to become lawyers, but they do need to understand that licensing is a permission boundary.

Gitignore And Environment Files

A .gitignore file tells Git which untracked files should normally stay out of commits. It is not a security system, because it does not remove files that were already tracked, and it does not stop someone from forcing a file into a commit. It is a workflow guardrail.

In PHP projects, .gitignore commonly excludes vendor/, local environment files, logs, caches, build output, IDE metadata when not shared, coverage output, and temporary files. The exact choices depend on the project. Some generated files belong in Git because they are source artifacts for a static site or package. Some IDE files belong in Git when the team intentionally shares project settings. The rule is not ignore everything generated; the rule is track source and intentionally shared configuration, ignore local state and reproducible output.

Environment files need special discipline. A real .env may contain database passwords, API tokens, mail credentials, encryption keys, or service URLs. It should not be committed. A .env.example or .env.dist should be committed with safe placeholder values and comments that explain required variables. That lets a new developer configure the project without copying secrets from a private chat.

Secret Recovery

If a secret is committed, the first fix is rotation or revocation, not cosmetic cleanup. Removing the secret from the latest commit does not invalidate copies already pulled, cached, logged, forked, or scanned. Rotate the credential, investigate where it was used, then decide whether history cleanup is needed. GitHub provides secret-scanning features in supported contexts, but no scanner replaces careful review and least-privilege credentials.

A good repository also limits blast radius. Use separate credentials for local development, staging, production, and CI. Do not share one all-powerful token between laptops and GitHub Actions. Prefer short-lived or narrowly scoped credentials where the platform supports them. Store deployment credentials in the deployment system's secret store, not in README instructions, committed scripts, or issue comments.

Issues, Security Notes, And Maintenance Status

Trust also comes from knowing how the project handles work. Issues are useful when they contain reproducible problems, decisions, and planned changes. Templates can ask for PHP version, operating system, reproduction steps, expected behavior, actual behavior, and logs with secrets removed. A security policy tells reporters how to disclose vulnerabilities privately when public issues would increase risk.

Maintenance status should be explicit. If the project is experimental, say so. If it is production-ready, state supported versions and support expectations. If it is archived, tell visitors why. A stale repository with no status note forces users to guess whether the maintainer is busy, done, or unaware of breakage.

Contribution And Support Files

Repository trust improves when maintainers explain how collaboration works. A CONTRIBUTING.md file can tell people how to set up the project, run checks, format code, open issues, propose large changes, and write pull requests. It should not be a wall of rules that scares away good contributors. The best version removes guessing: it tells a newcomer which branch to target, which commands must pass, what kind of issue should be opened first, and what information maintainers need for a useful review.

A SECURITY.md file serves a different purpose. It tells people how to report vulnerabilities responsibly, which versions are supported, and whether private reporting is available. Security reports should not be forced into public issues when that would give attackers a working exploit before maintainers can respond. Even small projects can include a simple security policy that says how to contact the maintainer and what information to include.

Issue and pull request templates can help, but only when they ask for information the maintainer will actually use. A bug report template for a PHP application might ask for PHP version, operating system, database engine, exact command or request, expected behavior, actual behavior, and a minimal reproduction. It should also remind reporters to remove secrets from logs. A pull request template might ask what changed, how it was tested, which issue it closes, and what risk the reviewer should focus on.

Preventing Secret Commits

Secret prevention works best in layers. A .gitignore keeps common local files out of normal commits. A .env.example gives developers a safe file to copy. Local hooks can catch obvious mistakes before commit. Repository or organization secret scanning can catch patterns that reach GitHub. Code review can catch context-specific values that scanners miss. None of these layers is perfect, so the team still needs a rotation playbook.

The repository should also avoid teaching unsafe setup habits. Documentation that says paste your production API key here normalizes dangerous work. Prefer instructions that point to a local .env, a secret manager, GitHub Actions secrets, or the hosting provider's configuration interface. In examples, use fake domains and placeholder values that cannot be mistaken for real credentials.

A strong review asks whether a new file changes the trust boundary. Adding .env.example is helpful. Adding .env is usually a defect. Adding a deployment script is useful only if credentials stay outside the file. Adding a badge is useful only if it links to an authoritative current status. Adding a license is useful only if the owner has the right to license the code.

Verification And Review

Review repository trust by opening the project as a stranger. Can you describe what it does in one sentence? Can you install it without private knowledge? Can you tell whether you may reuse it? Can you configure it without real secrets? Can you see how tests run? Can you report a bug or vulnerability? Can you tell whether the project is maintained?

The learner should be able to write a useful README, choose a license strategy, design .gitignore and .env.example boundaries, treat badges as claims, recover correctly from committed secrets, and review a repository for collaboration trust before asking others to use it.

# Invoice Portal

Invoice Portal is a PHP application for creating and approving invoices.

## Status

Maintained for internal use. Supports PHP 8.3+ and PostgreSQL 16.

## Requirements

- PHP 8.3+
- Composer
- PostgreSQL

## Installation

Run `composer install`.

## Configuration

Copy `.env.example` to `.env` and fill in local values. Never commit `.env`.

## Database

Create a local database and run migrations with the documented command.

## Testing

Run the test suite before opening a pull request.

## Deployment

Deployments are owned by the operations team and run through the documented CI workflow.