Repository Template

A minimal starting point for a basic repository. 🌊 🏄 🚀 🛸 🪐 🌌 👽

🌵 Project structure

Note

tree -a -F -L 3 -I '.git|.vscode' --gitignore --dirsfirst .

./
├── .github/
│   ├── workflows/
│   │   ├── ci.yaml
│   │   ├── conventional-commit.yaml
│   │   ├── create-labels.yaml
│   │   ├── dependabot-tests.yaml
│   │   ├── import-csv-issues.yaml
│   │   ├── pre-commit.yaml
│   │   ├── publish.yaml
│   │   ├── release.yaml
│   │   └── repository-created.yaml
│   ├── CODEOWNERS
│   └── dependabot.yml
├── .editorconfig
├── .gitignore
├── .markdownlint.json
├── .pre-commit-config.yaml
├── .prettierignore
├── .prettierrc
├── LICENSE
├── README.md
├── TODO.csv
└── TODO.example.csv

✅ Good first tasks

• 1️⃣ Create your repo: Use this template to create your own repo.

• 2️⃣ Create some labels: Run the Create Labels workflow to create some additional useful labels.

• 3️⃣ Create some issues: Run the Import Issues from CSV workflow to import first issues using the provided sample TODO.csv.

• 4️⃣ Customize your README.md (this file): Customize the README.md file to include project-specific information and instructions.

• 5️⃣ Complete the Dependabot Test: Review, approve, and merge the Pull Request (PR) generated by dependabot.

  The PR should have a title similar to the following:

  chore(deps): bump actions/checkout from 3 to X
  

---

🚀 Getting started

🅰️ Option "A": Use this template

1. Click the Use this template button at the top of the repository
2. Select Create a new repository
3. Select an owner and name for your new repository
4. Click Create repository
5. Clone your new repository

Important

Make sure to update the README.md and the LICENSE files accordingly.

🅱️ Option "B": Clone this repo

git clone git@github.com:stairwaytowonderland/repository-template.git

Create a new repository from the command line

# Delete the .git folder from cloned project
rm -rf .git

# Overwrite README with your content
echo "# Repository Template" > README.md

# Initialize new git local repository
git init

# Set default branch
git branch -M main

# Make first commit empty to allow easier rebasing
git commit --no-verify --allow-empty -m "chore: initial empty commit"

# Install pre-commit hooks
# (make sure `pre-commit` is installed ... install it using `pip` or `brew`)
pre-commit install

# Add all files (make sure your .gitignore file is properly configured)
git add .

# Second commit
git commit -m "chore: adding initial files"

# Set remote ...
# To update the url (instead of add), use `git remote set-url origin <GIT_URL>`
git remote add origin git@github.com:<user-or-org>/<new-existing-repo>.git

# Push to remote
git push -u origin main

📦 Releasing

This template uses semantic-release with the conventionalcommits preset by default.

🏷️ Tags/Releases

The creation of tags and releases is handled automatically by the pre-configured workflows.

Default package.json and .releaserc files will be used instead of being included in this template, however those files can be copied into this project for additional customizations, such as including a CHANGELOG.

Tip

In most cases, only the .releaserc needs to by copied/customized.

📃 Including a CHANGELOG

To have the generated CHANGELOG automatically committed:

1. Copy the default .releaserc file into your project.

2. Add the @semantic-release/git plugin configuration to the end of the plugins section in your .releaserc:

   [
     "@semantic-release/git",
     {
       "assets": ["CHANGELOG.md"],
       "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
     }
   ]

Note

If using an altered or different .releaserc file, you must also ensure the @semantic-release/changelog plugin is configured:

[
  "@semantic-release/changelog",
  {
    "changelogFile": "CHANGELOG.md"
  }
]

🔌 "RC" Plugin ordering

Important

The order of plugins DOES matter in the release configuration file (.releaserc)!

The @semantic-release/changelog plugin is typically one of the first in the plugins array, after semantic-release-export-data but before @semantic-release/commit-analyzer.

🖌️ Further customizations

🖋️ Contributing details

For customized contributing details, create a CONTRIBUTING.md in this repo:

echo "# Contributing Guidelines" > CONTRIBUTING.md

Tip

You may copy this organization's CONTRIBUTING.md file as a starting point.

🐞 Issues and PRs

For simplicity reasons, this template repo doesn't include the ISSUE_TEMPLATE and PULL_REQUEST_TEMPLATE (.md) files.

Note

If using this template in another org, or to add those files to your project for futher customization, copy them from this organization's special .github repo.

🏄 Essential tools

• Visual Studio Code (a.k.a. VS Code)
• EditorConfig
• pre-commit
• Prettier

  📝 Note: For a more customized experience, some files might need to be excluded from Prettier.

  See the official docs for details on ignoring code.

---

✨ Contributing

🤖 Commit Message Guidelines

• Write clear, concise commit messages that follow the  standard.

• The allowed prefixes for this project are the following:

  [
    "build",
    "chore",
    "ci",
    "docs",
    "feat",
    "fix",
    "perf",
    "refactor",
    "revert",
    "style",
    "test"
  ]

Note

See Contributing Guidelines for more information.