1. Clone this repo: git clone [email protected]:gravitational/rev-tech.git
2. Create a feature branch: git switch -c feature/my-awesome-demo.
3. Add your work under the right top‑level folder (see below), and include:
   • README.md (how to run/use)
   • sample config: .env.example (no secrets!)
   • quick test or smoke script if applicable
4. Open a Pull Request (PR) to main. Request reviewers.
5. Address comments; reviews are in, merge (squash).

• Rev Engineering Common Repo
  • TL;DR (1‑minute start)
  • Table of Contents
  • What lives here
  • Repository structure
  • Conventions & required files
  • Cloning & submitting a PR
    • PR expectations
  • Contribution checklist
  • Issue labels & triage
  • Best Practices
    • Do's
    • Don'ts
  • FAQ & common pitfalls
    • Advanced Git identity setup

• use-cases/: Sanitized, customer‑agnostic patterns that show what to build and why.
• proof-of-concepts/: Short‑lived, experimental demos proving feasibility.
• templates/: Production‑grade starter kits and reusable snippets for common scenarios.
• integrations/: Connectors and adapters to third‑party products/platforms.
• docs/: Any integration, solution, poc, etc that does not require code.
• tools/: Helper scripts to streamline workflows.
• archive/: Outdated code, useful for reference only.

Rule of thumb:

• If it’s reusable → templates/ or integrations/.
• If it’s storytelling/pattern → use-cases/.
• If it’s experimental or unproven → proof-of-concepts/.

.
├─ use-cases/
│  └─ <kebab-name>/
│     ├─ README.md
│     <IaC>/
│     ├─ README.md
├─ proof-of-concepts/
│  └─ <kebab-name>/
│     ├─ README.md
│     <api-integration>/
│     ├─ README.md
├─ templates/
│  └─ <kebab-name>/
│     ├─ README.md
│     <configurations>/
│     ├─ README.md
├─ integrations/
│  └─ <vendor>-<product>/
│     ├─ README.md
│     <slack>/
│     ├─ README.md
├─ tools/
│     ├── setup/
│     └── testing/
├─ docs/
├─ archive
│     └── README.md
├─ .github/
│  ├─ workflows/
│  ├─ ISSUE_TEMPLATE/
│  └─ PULL_REQUEST_TEMPLATE.md

Naming: use kebab‑case for folders; keep names concise and descriptive. Languages: multistack welcome (Python/Node/Go/…); keep each example self‑contained.

Every contribution (use‑case, POC, template, or integration) must include:

1. README.md (how to use it)

   • Purpose & audience
   • Prerequisites (versions, accounts)
   • Setup (step‑by‑step)
   • How to run (commands)
   • Expected output/screenshots
   • Troubleshooting
   • Support/owners

2. .env.example (if any runtime config is needed)

   # Copy to .env and fill values locally. Never commit real secrets.
   API_BASE_URL=https://api.example.com
   API_KEY=$$NOT_YOUR_API_KEY_HERE$$

1. First-time setup (needed only once)

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

2. Clone the repository:

git clone [email protected]:gravitational/rev-tech.git
cd rev-tech

3. Create a branch on the repository:

git switch -c feature/<short-title>

4. Do work and push to the branch:

git status
git add path/to/files
git commit -m "feat(demos): add awesome demo with README"
git push -u origin feature/my-awesome-demo

5. Go to the browser and switch to your branch, click Create Pull Request.

• Clear title: feat(templates): kafka ingest starter
• Description: what/why, setup summary, screenshots if useful
• Tick the Contribution checklist (below)
• Request reviewers

Before opening (or merging) a PR:

• Placed content in the correct top‑level folder (use-cases/, proof-of-concepts/, templates/, integrations/)
• Added README.md with usage & troubleshooting
• Requested reviews
• PR title uses a sensible prefix (e.g., feat:, fix:, docs:, add:, update:, remove:)

Recommended labels:

• type: use-case, poc, template, integration, docs
• status: draft, review, help-wanted, blocked, good-first-issue
• area: data, streaming, auth, ui, infra, cloud/<provider>, vendor/<name>

• ✅ Always test your code/configs before committing
• ✅ Keep customer data anonymized
• ✅ Use meaningful commit messages
• ✅ Update existing solutions rather than duplicating
• ✅ Tag your submissions with relevant keywords
• ✅ Include error handling in scripts
• ✅ Document any dependencies clearly

• ❌ Don't commit customer credentials or sensitive data
• ❌ Don't commit large binary files (use Git LFS if needed)
• ❌ Don't work directly on the main branch
• ❌ Don't merge your own PRs without review
• ❌ Don't forget to pull the latest changes before starting work

Basic command quick list:

• “My branch is behind main.” git fetch origin && git rebase origin/main (or merge if you prefer).
• “Accidentally committed a secret.” Remove it, rotate the secret, and contact a repo admin to purge history. (Don’t rely solely on git revert; secrets may persist in history.)
• “Merge conflicts!” Update your branch (rebase/merge) and use your IDE’s conflict tool. Keep commits small to minimize conflicts.

It is recommended that you set up Git to recognize both your personal repositories and your work-related repositories automatically. If it doesn't exist, create .config/git/ and create your main config file:

mkdir -p .config/git
touch .config/git/config
vi .config/git/config

Once you are editing the file, it should have content similar to this:

[user]
    name = Boris 'B' Kurktchiev
    # set to your normal GitHub email
    email = [email protected]
    signingkey = /Users/boris/.ssh/id_rsa.pub
# this include is important, you can have as many of these as includes as you want with different identities
# and matches for different orgs/repos
[includeIf "hasconfig:remote.*.url:[email protected]:gravitational/**"]
    path = config-work
[core]
    excludesfile = ~/.gitignore_global
    quotepath = false
    # set to your preferred code editor
    editor = code --wait -r
[push]
    default = simple
[filter "lfs"]
    clean = git-lfs clean -- %f
    smudge = git-lfs smudge -- %f
    required = true
    process = git-lfs filter-process
[pager]
    branch = false
[pull]
    rebase = true
[credential]
   # this uses the MacOS Keychain for password store
    helper = osxkeychain
[gpg]
    format = ssh
[gpg "ssh"]
   # if you store your SSH keys in 1Password, leave this here; otherwise, remove
    program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign
[commit]
    gpgsign = true
[url "ssh://[email protected]/"]
    insteadOf = https://github.com/
[init]
    defaultBranch = main

Now, in the same .config/git directory, create a second file and name it config-work:

touch .config/git/config-work
vi .config/git/config-work

The contents should look like this:

[user]
  # set to your work email
  email = [email protected]

Now, when you edit any repositories under the gravitational org, it will automatically use your work e-mail, while using your normal git for everything else.