diff --git a/.github/.release-please-manifest.json b/.github/.release-please-manifest.json new file mode 100644 index 000000000..c3f146397 --- /dev/null +++ b/.github/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "1.2.0" +} diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..b9da93074 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,79 @@ +# This is a comment. +# Each line is a file pattern followed by one or more owners. + +# These owners will be the default owners for everything in +# the repo. Unless a later match takes precedence, +# @global-owner1 and @global-owner2 will be requested for +# review when someone opens a pull request. +# * @global-owner1 @global-owner2 + +# Order is important; the last matching pattern takes the most +# precedence. When someone opens a pull request that only +# modifies JS files, only @js-owner and not the global +# owner(s) will be requested for a review. +# *.js @js-experts #This is an inline comment. + +# You can also use email addresses if you prefer. They'll be +# used to look up users just like we do for commit author +# emails. +# *.go docs@example.com + +# Teams can be specified as code owners as well. Teams should +# be identified in the format @org/team-name. Teams must have +# explicit write access to the repository. In this example, +# the octocats team in the octo-org organization owns all .txt files. +# *.txt @octo-org/octocats + +# Terraform Files +# *.tf @terraform-experts +# .terraform-docs.yaml @terraform-experts + +# SQL Files +# *.sql @sql-experts +# *.sqlproj @sql-experts + +# SSIS Files +# *.dtsx @ssis-experts +# *.params @ssis-experts +# *.conmgr @ssis-experts +# *.database @ssis-experts +# *.dtproj @ssis-experts + +# In this example, @doctocat owns any files in the build/logs +# directory at the root of the repository and any of its +# subdirectories. +# /build/logs/ @doctocat + +# The `docs/*` pattern will match files like +# `docs/getting-started.md` but not further nested files like +# `docs/build-app/troubleshooting.md`. +# docs/* docs@example.com + +# In this example, @octocat owns any file in an apps directory +# anywhere in your repository. +# apps/ @octocat + +# In this example, @doctocat owns any file in the `/docs` +# directory in the root of your repository and any of its +# subdirectories. +# /docs/ @doctocat + +# In this example, any change inside the `/scripts` directory +# will require approval from @doctocat or @octocat. +# /scripts/ @doctocat @octocat + +# In this example, @octocat owns any file in a `/logs` directory such as +# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes +# in a `/logs` directory will require approval from @octocat. +# **/logs @octocat + +# In this example, @octocat owns any file in the `/apps` +# directory in the root of your repository except for the `/apps/github` +# subdirectory, as its owners are left empty. +# /apps/ @octocat +# /apps/github + +# Technical Steering Committee should be in charge of reviewing any changes +# to automations (because they should be centralized, shared, and standardized) +# as well as changes to key governance and control files or documents +# .github/* @tsc diff --git a/.github/ISSUE_TEMPLATE/bug-report---.md b/.github/ISSUE_TEMPLATE/bug-report---.md index e74e7d0d0..1aadaf7f7 100644 --- a/.github/ISSUE_TEMPLATE/bug-report---.md +++ b/.github/ISSUE_TEMPLATE/bug-report---.md @@ -6,17 +6,22 @@ labels: bug --- ## Describe the bug + A clear and concise description of what the bug is. ### Steps to reproduce + Steps to reproduce the behavior. ### Expected behavior + A clear and concise description of what you expected to happen. ### Environment - - OS: [e.g. Arch Linux] - - Other details that you think may affect. + +- OS: [e.g. Arch Linux] +- Other details that you think may affect. ### Additional context -Add any other context about the problem here. \ No newline at end of file + +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature-request---.md b/.github/ISSUE_TEMPLATE/feature-request---.md index 3bd987c1c..355cf62b1 100644 --- a/.github/ISSUE_TEMPLATE/feature-request---.md +++ b/.github/ISSUE_TEMPLATE/feature-request---.md @@ -6,10 +6,13 @@ labels: enhancement --- ## Summary + Brief explanation of the feature. ### Basic example + Include a basic example or links here. ### Motivation -Why are we doing this? What use cases does it support? What is the expected outcome? \ No newline at end of file + +Why are we doing this? What use cases does it support? What is the expected outcome? diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..5f8a17634 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: 'github-actions' + directory: '/.github/workflows' + schedule: + interval: 'daily' + labels: + - '๐Ÿ“ฆ Dependencies' + - '๐Ÿš€ CI/CD' + commit-message: + prefix: 'chore(deps-ci): Update GHA Dependencies' diff --git a/.github/pr-scope-labeler.yml b/.github/pr-scope-labeler.yml new file mode 100644 index 000000000..a95c0d499 --- /dev/null +++ b/.github/pr-scope-labeler.yml @@ -0,0 +1,71 @@ +# This file is used to configure the PR Scope Labeler action +# in .github/workflows/pr-controls.yml +๐Ÿ’ป Source: + - changed-files: + - any-glob-to-any-file: + - src/** + +๐Ÿงช Tests: + - changed-files: + - any-glob-to-any-file: + - tests/** + - vitest*config*.ts + - .env.test + +๐Ÿ“ Documentation: + - changed-files: + - any-glob-to-any-file: + - docs/** + - README* + - images/** + +๐Ÿณ Build: + - changed-files: + - any-glob-to-any-file: + - .dockerignore + - Dockerfile + - docker-compose.yml + - .nvmrc + - .swcrc + - tsconfig*.json + +โš™๏ธ Configuration: + - changed-files: + - any-glob-to-any-file: + - .dockerignore + - .editorconfig + - .env* + - .eslintignore + - .eslintrc + - .gitignore + - .npmignore + - .npmrc + - .nvmrc + - .prettierignore + - .swcrc + - .yamllint.yml + - '*config*.ts' + - '*.config.mjs' + - tsconfig*.json + +๐Ÿ“ฆ Dependencies: + - changed-files: + - any-glob-to-any-file: + - package.json + - package-lock.json + +๐Ÿš€ CI/CD: + - changed-files: + - any-glob-to-any-file: + - .github/workflows/** + - .github/dependabot.yml + - .github/pr-scope-labeler.yml + +๐Ÿ”ง Github Configuration: + - changed-files: + - any-glob-to-any-file: + - .github/ISSUE_TEMPLATE/** + - .github/CODEOWNERS + - .github/PULL_REQUEST_TEMPLATE.md + - .github/settings.yml + - .github/workflows/repo-gov.yml diff --git a/.github/release-please-config.json b/.github/release-please-config.json new file mode 100644 index 000000000..581ee5438 --- /dev/null +++ b/.github/release-please-config.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "release-search-depth": 400, + "group-pull-request-title-pattern": "chore${scope}: Release ${component} v${version}", + "pull-request-title-pattern": "chore${scope}: Release ${component} v${version}", + "packages": { + ".": { + "pull-request-title-pattern": "chore${scope}: Release v${version}", + "tag-separator": "@", + "include-v-in-tag": true, + "changelog-path": "CHANGELOG.md", + "release-type": "simple", + "bump-minor-pre-major": false, + "bump-patch-for-minor-pre-major": false, + "draft": false, + "prerelease": false, + "exclude-paths": [".github"], + "include-component-in-tag": false, + "extra-files": [] + } + }, + "plugins": [] +} diff --git a/.github/settings.yml b/.github/settings.yml new file mode 100644 index 000000000..bbcde8825 --- /dev/null +++ b/.github/settings.yml @@ -0,0 +1,142 @@ +# See https://github.com/marketplace/actions/manage-administrative-repository-settings-from-pull-requests for details +collaborators: + # Especially useful if the repository is private or part of an organization + +settings: + # Useful if you have default repo settings you wish to apply when creating a new repo + +labels: + # Useful to blow out a lot of standard labels and make busy PR / Issue screens easier on eyes + # Colors can be researched at https://hexcolor16.com + - name: bug + description: Bug identified + color: D73A4A + new_name: ๐Ÿž Bug + + - name: documentation + description: Improvements or additions to documentation + color: 228AFF # 0075ca + new_name: ๐Ÿ“ Documentation + + - name: duplicate + description: This issue or pull request already exists + color: 7A5901 # cfd3d7 + new_name: ๐Ÿ’ฉ Duplicate + + - name: enhancement + description: Feature added in the PR + color: A2EEEF + new_name: โœ… Feature + + - name: 'good first issue' + description: Good for newcomers + color: 7057ff + new_name: ๐Ÿ‘ถ Good First Issue + + - name: 'help wanted' + description: Extra attention is needed + color: 008672 + new_name: ๐Ÿ†˜ Help Wanted + + - name: invalid + description: This doesn't seem right + color: E4E669 + new_name: ๐Ÿšซ Invalid + + - name: question + description: Further information is requested + color: D876E3 + new_name: โ“ Question + + - name: wontfix + description: This will not be worked on + color: FFFFFF + new_name: ๐Ÿ™…โ€โ™‚๏ธ Wontfix + + - name: โš ๏ธ Breaking Change + description: Breaking change in the PR + color: F1F800 + + - name: ๐Ÿณ Build + description: Indicates the change is related to the build + color: 0FD4DA + + - name: ๐Ÿš€ CI/CD + description: Indicates the change is related to CI/CD workflows + color: FF4D4D + + - name: โš™๏ธ Configuration + description: Indicates the scope is related to the configuration + color: BDBDBD + + - name: ๐Ÿ“ฆ Dependencies + description: Pull requests that update a dependency file + color: 228AFF + + - name: ๐Ÿ‘€ Feature Requested + description: Request for a feature + color: 07D90A + + - name: ๐Ÿ•ต๐Ÿป Fix + description: Fix applied in the PR + color: F4D03F + + - name: ๐Ÿ”ง Github Configuration + description: Indicates the change is related to github settings + color: '555555' + + - name: ๐Ÿ’ป Source + description: Indicates the scope is related to the own service logic + color: FDC720 + + - name: ๐Ÿงช Tests + description: Indicates the scope is related to the tests + color: 088E26 + + - name: ๐Ÿคฉ size/xs + description: Pull request size XS + color: 27AE60 + + - name: ๐Ÿฅณ size/s + description: Pull request size S + color: 2ECC71 + + - name: ๐Ÿ˜Ž size/m + description: Pull request size M + color: F1C40F + + - name: ๐Ÿ˜– size/l + description: Pull request size L + color: F39C12 + + - name: ๐Ÿคฏ size/xl + description: Pull request size XL + color: E67E22 + + - name: ignore-for-release + description: Ignore pull request for a new release + color: EDEDED + + - name: 'autorelease: tagged' + description: Used by release-please to indicate a release has been tagged + color: EDEDED + + - name: 'autorelease: pending' + description: Used by release-please to indicate a release is pending + color: EDEDED + +branch_protections: + # Great if you have standards of practice to require certain checks before merging PRs + +environments: + # Useful if you have a multi-stage deployment process and want to enforce certain checks before deploying to production + +secrets: + # Useful if you have a standard set of secrets you want to ensure are always present in the repository + +variables: + # Useful if you have a standard set of environment variables you want to ensure are always present in the repository + +batch_file_operations: + # Useful if you have a standard set of files you want to ensure are always present in the repository + # or if you want to centrally manage common / shared files across multiple repositories diff --git a/.github/workflows/pr-controls.yml b/.github/workflows/pr-controls.yml new file mode 100644 index 000000000..1e3c5ccbd --- /dev/null +++ b/.github/workflows/pr-controls.yml @@ -0,0 +1,101 @@ +name: 'Controls to Standardize Pull Requests' + +on: + pull_request: + paths: + - '.github/workflows/pr-controls.yml' + # Note, pull_request_target is used to ensure that the action runs + # with the permissions and secrets defined in the repository + # however, if this workflow is updated in source branch or fork, it will run the current definition + # in the target branch. We use the pull_request above to validate the changes to the new definition. + # https://stackoverflow.com/questions/74957218/what-is-the-difference-between-pull-request-and-pull-request-target-event-in-git + pull_request_target: + types: + - opened + - edited + - synchronize + - reopened + +jobs: + pr_title: + name: 'Check PR Title ๐Ÿ“' + runs-on: [ "ubuntu-latest" ] + permissions: + contents: read + steps: + #TODO: Deprecated NodeJS Version + - name: Clean Agent Workspace + uses: tiacsys/clean-after-action@v3.0.0 + + - name: Conventional Commits + uses: amannn/action-semantic-pull-request@v5.5.3 + env: + GITHUB_TOKEN: ${{ github.token }} + with: + # Configure which types are allowed. + # Default: https://github.com/commitizen/conventional-commit-types + types: | + fix + feat + docs + ci + chore + # Configure that a scope must always be provided. + requireScope: false + # Configure additional validation for the subject based on a regex. + # This example ensures the subject starts with an uppercase character. + subjectPattern: ^[A-Z].+$ + # If `subjectPattern` is configured, you can use this property to override + # the default error message that is shown when the pattern doesn't match. + # The variables `subject` and `title` can be used within the message. + subjectPatternError: | + The subject "{subject}" found in the pull request title "{title}" + didn't match the configured pattern. Please ensure that the subject + starts with an uppercase character. + # For work-in-progress PRs you can typically use draft pull requests + # from Github. However, private repositories on the free plan don't have + # this option and therefore this action allows you to opt-in to using the + # special "[WIP]" prefix to indicate this state. This will avoid the + # validation of the PR title and the pull request checks remain pending. + # Note that a second check will be reported if this is enabled. + wip: false + # When using "Squash and merge" on a PR with only one commit, GitHub + # will suggest using that commit message instead of the PR title for the + # merge commit, and it's easy to commit this by mistake. Enable this option + # to also validate the commit message for one commit PRs. + validateSingleCommit: true + + pr_labels: + name: Apply Labels + runs-on: [ "ubuntu-latest" ] + permissions: + contents: read + pull-requests: write + steps: + #TODO: Deprecated NodeJS Version + - name: Clean Agent Workspace + uses: tiacsys/clean-after-action@v3.0.0 + + - name: 'PR Scope ๐Ÿ”ญ๐Ÿงง' + uses: actions/labeler@v5.0.0 + with: + configuration-path: .github/pr-scope-labeler.yml + + - name: 'PR Size ๐Ÿฏ' + uses: codelytv/pr-size-labeler@v1.10.1 + with: + xs_label: '๐Ÿคฉ size/xs' + xs_max_size: '10' + s_label: '๐Ÿฅณ size/s' + s_max_size: '100' + m_label: '๐Ÿ˜Ž size/m' + m_max_size: '500' + l_label: '๐Ÿ˜– size/l' + l_max_size: '1000' + xl_label: '๐Ÿคฏ size/xl' + fail_if_xl: 'false' + message_if_xl: > + This PR exceeds the recommended size of 1000 lines. + Please make sure you are NOT addressing multiple issues with one PR. + Note this PR might be rejected due to its size. + files_to_ignore: 'package-lock.json *.lock docs/* dist/*' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000..d83b9866e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,22 @@ +name: Release + +on: + push: + # Sequence of patterns matched against refs/heads + branches: + - main + +jobs: + release: + name: 'Create Release PR ๐Ÿš€' + runs-on: ["ubuntu-latest"] + steps: + + - name: 'Release Please ๐ŸŽ‰' + uses: googleapis/release-please-action@v4.1.1 + with: + token: ${{ github.token }} + # only needed if you want these files loaded from a branch other than the default branch + target-branch: main + manifest-file: .github/.release-please-manifest.json + config-file: .github/release-please-config.json diff --git a/.github/workflows/repo-config.yml b/.github/workflows/repo-config.yml new file mode 100644 index 000000000..a44378f1b --- /dev/null +++ b/.github/workflows/repo-config.yml @@ -0,0 +1,55 @@ +name: ๐Ÿ”ง Repo Config + +# Controls when the workflow will run +on: + push: + paths: + - '.github/settings.yml' + - '.github/workflows/repo-config.yml' + + schedule: + # Everyday @ 0000 - https://crontab.cronhub.io/ + # Useful to ensure that when settings are changed temporarily, they are reverted back to the default + - cron: '0 0 * * *' + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "repo-manager" + repo-manager: + concurrency: + group: ${{ matrix.repo }}-${{ matrix.settings_file}} + cancel-in-progress: true + strategy: + matrix: + repo: + - self + settings_file: + - .github/settings.yml + fail-fast: false + + name: โš™๏ธ ${{ matrix.repo }} from ${{ matrix.settings_file }} + if: ${{ inputs.action != 'skip' && inputs.repos != '[]' }} + # The type of runner that the job will run on + runs-on: [ "ubuntu-latest" ] + permissions: + contents: read + pull-requests: write + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + #TODO: Deprecated NodeJS Version + - name: Clean Agent Workspace + uses: tiacsys/clean-after-action@v3.0.0 + + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout + uses: actions/checkout@v4.1.7 + + # Runs a single command using the runners shell + - name: Run RepoManager + if: '!cancelled()' # This is a workaround for a bug in the cancel-in-progress feature + uses: actuarysailor/gha-repo-manager@v2.2.3 + with: + repo: ${{ matrix.repo }} + action: 'apply' + settings_file: ${{ matrix.settings_file }} + token: ${{ github.token }} diff --git a/.github/workflows/repo-maint.yml b/.github/workflows/repo-maint.yml new file mode 100644 index 000000000..d597b8756 --- /dev/null +++ b/.github/workflows/repo-maint.yml @@ -0,0 +1,75 @@ +# Description: This workflow is used to maintain the repository by: +# closing stale issues and PRs that have not had any update in 10-days, +# locking issues and PRs that have been closed for 60-days, +# and marking issues and PRs older than 90-days as stale. +# All of these settings can be adjusted below. +name: 'Issue & PR Maintenance' +on: + + schedule: + - cron: '0 0 * * *' + + push: + paths: + - '.github/workflows/repo-maint.yml' + +jobs: + stale: + name: Close๐Ÿšช & Stale ๐Ÿ’ฉ + runs-on: [ "ubuntu-latest" ] + permissions: + issues: write + pull-requests: write + steps: + # TODO: Deprecated NodeJS Version + - name: Clean Agent Workspace + uses: tiacsys/clean-after-action@v3.0.0 + + - name: Stale Issues and PRs + uses: actions/stale@v6.0.1 + with: + repo-token: ${{ github.token }} + # Staling issues and PR's + days-before-stale: 90 + stale-issue-label: stale + stale-pr-label: stale + stale-issue-message: | + This issue has been automatically marked as stale because it has been open 90 days + with no activity. Remove stale label or comment or this issue will be closed in 10 days + stale-pr-message: | + This PR has been automatically marked as stale because it has been open 90 days + with no activity. Remove stale label or comment or this PR will be closed in 10 days + # Not stale if have this labels or part of milestone + exempt-issue-labels: bug,wip,on-hold + exempt-pr-labels: bug,wip,on-hold + exempt-all-milestones: true + # Close issue operations + # Label will be automatically removed if the issues are no longer closed nor locked. + days-before-close: 10 + delete-branch: true + close-issue-message: This issue was automatically closed because it remained marked as stale for 10 days + close-pr-message: This PR was automatically closed because remained marked as stale for 10 days + + lock: + name: Lock๐Ÿ”’ + runs-on: [ "ubuntu-latest" ] + permissions: + issues: write + pull-requests: write + steps: + #TODO: Deprecated NodeJS Version + - name: Clean Agent Workspace + uses: tiacsys/clean-after-action@v3.0.0 + + - name: Lock Threads + uses: dessant/lock-threads@v5.0.1 + with: + github-token: ${{ github.token }} + issue-comment: > + I'm going to lock this issue because it has been closed for _60 days_ โณ. This helps our maintainers find and focus on the active issues. + If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further. + issue-inactive-days: '60' + pr-comment: > + I'm going to lock this pull request because it has been closed for _60 days_ โณ. This helps our maintainers find and focus on the active issues. + If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further. + pr-inactive-days: '60' diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..e4f5d8603 --- /dev/null +++ b/.gitignore @@ -0,0 +1,33 @@ +# Node.js +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +package-lock.json + +# Python virtual environment +.venv/ +venv/ + +# Generated files +*.tmp + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# IDE files +.vscode/ +.idea/ +*.iml +*.swp +*.swo + +# Temporary files +*.tmp +*.temp diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index b58b603fe..000000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ diff --git a/.idea/Best-README-Template.iml b/.idea/Best-README-Template.iml deleted file mode 100644 index 24643cc37..000000000 --- a/.idea/Best-README-Template.iml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml deleted file mode 100644 index a55e7a179..000000000 --- a/.idea/codeStyles/codeStyleConfig.xml +++ /dev/null @@ -1,5 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index 86bd7988e..000000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 35eb1ddfb..000000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 000000000..fc6889933 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,32 @@ +{ + "MD013": { + "line_length": 80, + "code_blocks": false, + "tables": false, + "headings": false + }, + "MD033": { + "allowed_elements": [ + "a", + "div", + "img", + "h1", + "h2", + "h3", + "h4", + "h5", + "h6", + "p", + "br", + "strong", + "em", + "details", + "summary", + "ol", + "ul", + "li" + ] + }, + "MD041": false, + "MD034": false +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..4f24d99c3 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,39 @@ +fail_fast: false +minimum_pre_commit_version: "2.6.0" +repos: + # README Generator validation + - repo: https://github.com/actuarysailor/pre-commit-readme-generator + rev: v1.0.0 + hooks: + - id: readme-generator-update + args: [configs/example.json, README.md, BLANK_README.md] + + # Standard file checks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-merge-conflict + - id: check-yaml + - id: check-json + - id: check-added-large-files + - id: check-case-conflict + - id: mixed-line-ending + args: ['--fix=lf'] + + # Markdown linting + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.45.0 + hooks: + - id: markdownlint + args: ['--fix'] + exclude: '^CHANGELOG|BLANK_README\.md$' + + # JSON formatting + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v3.0.3 + hooks: + - id: prettier + types: [json] + args: ['--write'] diff --git a/BLANK_README.md b/BLANK_README.md index 4553aa479..216a7e046 100644 --- a/BLANK_README.md +++ b/BLANK_README.md @@ -1,5 +1,3 @@ - - - - + + + +
+ +

{{project.title}}

+ + Logo + + +
-[![Contributors][contributors-shield]][contributors-url] -[![Forks][forks-shield]][forks-url] -[![Stargazers][stars-shield]][stars-url] -[![Issues][issues-shield]][issues-url] -[![project_license][license-shield]][license-url] -[![LinkedIn][linkedin-shield]][linkedin-url] - - - -
- - Logo - -

project_title

+ +{{#badges.contributors}}[![Contributors][contributors-shield]][contributors-url]{{/badges.contributors}} +{{#badges.forks}}[![Forks][forks-shield]][forks-url]{{/badges.forks}} +{{#badges.stars}}[![Stargazers][stars-shield]][stars-url]{{/badges.stars}} +{{#badges.issues}}[![Issues][issues-shield]][issues-url]{{/badges.issues}} +{{#badges.license}}[![{{repository.license}}][license-shield]][license-url]{{/badges.license}} + +
+ +
+

- project_description + {{project.description}}
- Explore the docs ยป + + Explore the docs ยป +

- View Demo - · - Report Bug - · - Request Feature + + View Demo + + ยท + + Report Bug + + ยท + + Request Feature +

+
- - +
Table of Contents
    + + {{#sections.about.enabled}}
  1. About The Project + + {{#sections.built_with.enabled}} + {{/sections.built_with.enabled}} +
    2. + {{/sections.about.enabled}} + + + {{#sections.getting_started.enabled}}
  2. Getting Started
    3. + {{/sections.getting_started.enabled}} + + + {{#sections.usage.enabled}}
  3. Usage
    4. + {{/sections.usage.enabled}} + + + {{#sections.roadmap.enabled}}
  4. Roadmap
    5. + {{/sections.roadmap.enabled}} + + + {{#sections.contributing.enabled}}
  5. Contributing
    6. + {{/sections.contributing.enabled}} + + + {{#sections.license.enabled}}
  6. License
    7. + {{/sections.license.enabled}} + + + {{#sections.contact.enabled}}
  7. Contact
    8. + {{/sections.contact.enabled}} + + + {{#sections.acknowledgments.enabled}}
  8. Acknowledgments
    9. + {{/sections.acknowledgments.enabled}} + +
  9. FAQ
- - + +{{#sections.about.enabled}} + ## About The Project [![Product Name Screen Shot][product-screenshot]](https://example.com) -Here's a blank template to get started. To avoid retyping too much info, do a search and replace with your text editor for the following: `github_username`, `repo_name`, `twitter_handle`, `linkedin_username`, `email_client`, `email`, `project_title`, `project_description`, `project_license` +{{sections.about.content}}

(back to top)

- - + + +{{#sections.built_with.enabled}} ### Built With - -* [![Next][Next.js]][Next-url] -* [![React][React.js]][React-url] -* [![Vue][Vue.js]][Vue-url] -* [![Angular][Angular.io]][Angular-url] -* [![Svelte][Svelte.dev]][Svelte-url] -* [![Laravel][Laravel.com]][Laravel-url] -* [![Bootstrap][Bootstrap.com]][Bootstrap-url] -* [![JQuery][JQuery.com]][JQuery-url] + + +This section should list any major frameworks/libraries used to bootstrap your +project. Leave any add-ons/plugins for the acknowledgements section. Here are a +few examples. + + +{{#sections.built_with.frameworks}} +- [![{{name}}][{{name}}.shield]][{{name}}-url] +{{/sections.built_with.frameworks}} + + +{{/sections.built_with.enabled}} + +{{/sections.about.enabled}} +

(back to top)

- - + +{{#sections.getting_started.enabled}} + ## Getting Started -This is an example of how you may give instructions on setting up your project locally. -To get a local copy up and running follow these simple example steps. +This is an example of how you may give instructions on setting up your project +locally. To get a local copy up and running follow these simple example steps. ### Prerequisites -This is an example of how to list things you need to use the software and how to install them. -* npm +This is an example of how to list things you need to use the software and how +to install them. + + +{{#sections.getting_started.prerequisites}} +- {{name}} + ```sh - npm install npm@latest -g + {{command}} ``` +{{/sections.getting_started.prerequisites}} ### Installation -1. Get a free API Key at [https://example.com](https://example.com) -2. Clone the repo - ```sh - git clone https://github.com/github_username/repo_name.git - ``` -3. Install NPM packages - ```sh - npm install - ``` -4. Enter your API in `config.js` - ```js - const API_KEY = 'ENTER YOUR API'; - ``` -5. Change git remote url to avoid accidental pushes to base project - ```sh - git remote set-url origin github_username/repo_name - git remote -v # confirm the changes - ``` +_Below is an example of how you can instruct your audience on installing and +setting up your app. This template doesn't rely on any external dependencies +or services._ -

(back to top)

+{{#sections.getting_started.installation_steps}} +{{increment @index}}. {{{text}}}{{#if command}} + ```{{#if language}}{{language}}{{else}}sh{{/if}} + {{{command}}} + ``` +{{/if}} +{{/sections.getting_started.installation_steps}} + +{{/sections.getting_started.enabled}} + +

(back to top)

+ +{{#sections.usage.enabled}} + ## Usage -Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. +{{{sections.usage.content}}} _For more examples, please refer to the [Documentation](https://example.com)_ +{{/sections.usage.enabled}} +

(back to top)

- - + +{{#sections.roadmap.enabled}} + ## Roadmap -- [ ] Feature 1 -- [ ] Feature 2 -- [ ] Feature 3 - - [ ] Nested Feature + +{{#sections.roadmap.items}} +- [{{#if completed}}x{{else}} {{/if}}] {{text}} +{{#if subitems}} +{{#subitems}} + - [{{#if completed}}x{{else}} {{/if}}] {{text}} +{{/subitems}} +{{/if}} +{{/sections.roadmap.items}} + -See the [open issues](https://github.com/github_username/repo_name/issues) for a full list of proposed features (and known issues). +See the [open issues](https://github.com/{{repository.github_username}}/{{repository.repo_name}}/issues) +for a full list of proposed features (and known issues).

(back to top)

- - +{{/sections.roadmap.enabled}} + + +{{#sections.contributing.enabled}} + ## Contributing -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. +Contributions are what make the open source community such an amazing place to +learn, inspire, and create. Any contributions you make are **greatly appreciated**. -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". -Don't forget to give the project a star! Thanks again! +If you have a suggestion that would make this better, please fork the repo and +create a pull request. You can also simply open an issue with the tag +"enhancement". Don't forget to give the project a star! Thanks again! 1. Fork the Project 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the Branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request + +{{#sections.contributing.show_contributors}} -

(back to top)

- -### Top contributors: +### Top contributors - - contrib.rocks image + + contrib.rocks image - +{{/sections.contributing.show_contributors}} + +{{/sections.contributing.enabled}} + +

(back to top)

+ +{{#sections.license.enabled}} + ## License -Distributed under the project_license. See `LICENSE.txt` for more information. +Distributed under the {{repository.license}}. See `{{repository.license_file}}` for more information. +{{/sections.license.enabled}} +

(back to top)

- - -## Contact + +{{#sections.contact.enabled}} -Your Name - [@twitter_handle](https://twitter.com/twitter_handle) - email@email_client.com +## Contact -Project Link: [https://github.com/github_username/repo_name](https://github.com/github_username/repo_name) +| | | +|:---:|:---| +| {{contact.name}} | **{{contact.name}}** | +| ๐Ÿ“ง | [{{contact.email}}](mailto:{{contact.email}}) | +| ๐Ÿ™ | [@{{repository.github_username}}](https://github.com/{{repository.github_username}}) | +{{#each contact.socials}}{{#if enabled}}| {{icon}} | [{{platform}}]({{url}}) | +{{/if}}{{/each}} +**Project Link:** [https://github.com/{{repository.github_username}}/{{repository.repo_name}}](https://github.com/{{repository.github_username}}/{{repository.repo_name}}) +{{/sections.contact.enabled}} +

(back to top)

- - + +{{#sections.acknowledgments.enabled}} + ## Acknowledgments -* []() -* []() -* []() - -

(back to top)

+Use this space to list resources you find helpful and would like to give credit +to. I've included a few of my favorites to kick things off! + +{{#sections.acknowledgments.items}} +- [{{name}}]({{url}}) +{{/sections.acknowledgments.items}} + +{{/sections.acknowledgments.enabled}} + +

(back to top)

-[contributors-shield]: https://img.shields.io/github/contributors/github_username/repo_name.svg?style=for-the-badge -[contributors-url]: https://github.com/github_username/repo_name/graphs/contributors -[forks-shield]: https://img.shields.io/github/forks/github_username/repo_name.svg?style=for-the-badge -[forks-url]: https://github.com/github_username/repo_name/network/members -[stars-shield]: https://img.shields.io/github/stars/github_username/repo_name.svg?style=for-the-badge -[stars-url]: https://github.com/github_username/repo_name/stargazers -[issues-shield]: https://img.shields.io/github/issues/github_username/repo_name.svg?style=for-the-badge -[issues-url]: https://github.com/github_username/repo_name/issues -[license-shield]: https://img.shields.io/github/license/github_username/repo_name.svg?style=for-the-badge -[license-url]: https://github.com/github_username/repo_name/blob/master/LICENSE.txt -[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 -[linkedin-url]: https://linkedin.com/in/linkedin_username -[product-screenshot]: images/screenshot.png -[Next.js]: https://img.shields.io/badge/next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white -[Next-url]: https://nextjs.org/ -[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB -[React-url]: https://reactjs.org/ -[Vue.js]: https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vuedotjs&logoColor=4FC08D -[Vue-url]: https://vuejs.org/ -[Angular.io]: https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white -[Angular-url]: https://angular.io/ -[Svelte.dev]: https://img.shields.io/badge/Svelte-4A4A55?style=for-the-badge&logo=svelte&logoColor=FF3E00 -[Svelte-url]: https://svelte.dev/ -[Laravel.com]: https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white -[Laravel-url]: https://laravel.com -[Bootstrap.com]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white -[Bootstrap-url]: https://getbootstrap.com -[JQuery.com]: https://img.shields.io/badge/jQuery-0769AD?style=for-the-badge&logo=jquery&logoColor=white -[JQuery-url]: https://jquery.com + +[contributors-shield]: https://img.shields.io/github/contributors/{{repository.github_username}}/{{repository.repo_name}}.svg?style=for-the-badge +[contributors-url]: https://github.com/{{repository.github_username}}/{{repository.repo_name}}/graphs/contributors +[forks-shield]: https://img.shields.io/github/forks/{{repository.github_username}}/{{repository.repo_name}}.svg?style=for-the-badge +[forks-url]: https://github.com/{{repository.github_username}}/{{repository.repo_name}}/network/members +[stars-shield]: https://img.shields.io/github/stars/{{repository.github_username}}/{{repository.repo_name}}.svg?style=for-the-badge +[stars-url]: https://github.com/{{repository.github_username}}/{{repository.repo_name}}/stargazers +[issues-shield]: https://img.shields.io/github/issues/{{repository.github_username}}/{{repository.repo_name}}.svg?style=for-the-badge +[issues-url]: https://github.com/{{repository.github_username}}/{{repository.repo_name}}/issues +[license-shield]: https://img.shields.io/github/license/{{repository.github_username}}/{{repository.repo_name}}.svg?style=for-the-badge +[license-url]: https://github.com/{{repository.github_username}}/{{repository.repo_name}}/blob/master/{{repository.license_file}} +[product-screenshot]: {{project.screenshot_path}} +{{#sections.built_with.frameworks}} +[{{name}}.shield]: {{badge}} +[{{name}}-url]: {{url}} +{{/sections.built_with.frameworks}} diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ece0c3bd..680c6de5c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,28 +1,55 @@ # Changelog +## [1.2.0](https://github.com/actuarysailor/template-readme-only/compare/v1.1.1...v1.2.0) (2025-08-12) + + +### Features + +* Add FAQ per Issue [#142](https://github.com/actuarysailor/template-readme-only/issues/142) ([fc88a2f](https://github.com/actuarysailor/template-readme-only/commit/fc88a2f7273e096ef954160a76e105dfb7f65ddb)) +* Marked tasks complete on the roadmap ([e7e4883](https://github.com/actuarysailor/template-readme-only/commit/e7e4883c9dfabddc0f0905dddbb816d50518125c)) +* Modified BLANK_README.md to use readme-config.json ([956317b](https://github.com/actuarysailor/template-readme-only/commit/956317bacd034073722345f2a087b2dad4fa2c1f)) +* Readme from components ([e813e9b](https://github.com/actuarysailor/template-readme-only/commit/e813e9bfed10366e2ac763f4601e307d3bd0cc51)) + + +### Bug Fixes + +* add alt tag to contributors img ([f874681](https://github.com/actuarysailor/template-readme-only/commit/f874681ebc566728d96e3100cd6683678038ad82)) +* Change name attribute to id for back to top link ([#122](https://github.com/actuarysailor/template-readme-only/issues/122)) ([3d3138f](https://github.com/actuarysailor/template-readme-only/commit/3d3138fb65eaf42d14db9525ab16644f94686058)) +* Cleanup the files after merge ([ca4a79b](https://github.com/actuarysailor/template-readme-only/commit/ca4a79b79d970e91f6e5fbb3ec90ea3e0386c4d1)) +* License URL Issue ([37ebfb8](https://github.com/actuarysailor/template-readme-only/commit/37ebfb89e55a345215c6302bf44716a2abf7ea89)) +* Made it more clearly address questions in [#142](https://github.com/actuarysailor/template-readme-only/issues/142) ([95b65aa](https://github.com/actuarysailor/template-readme-only/commit/95b65aa0dadd4681678eb2a463cf70b9c7603afa)) +* **PR-#69:** add changing git remote url to installation ([09528da](https://github.com/actuarysailor/template-readme-only/commit/09528da76ad03c0585b5d80cd73506de96955211)) +* Readme Template ([28a5c9d](https://github.com/actuarysailor/template-readme-only/commit/28a5c9d3f2897372589e96742972b4beb59378e6)) +* Renamed standard config file to example.json and added additional configs ([2a7c6cf](https://github.com/actuarysailor/template-readme-only/commit/2a7c6cf809ad4a68c22b1f50ea1ec1fbeb1ed22f)) +* Restored dropped text ([e90e79a](https://github.com/actuarysailor/template-readme-only/commit/e90e79a2004dafdf83b0f4521347a526357a2a47)) +* revert align tags ([e2266cd](https://github.com/actuarysailor/template-readme-only/commit/e2266cdf17db9cbc3efaba2a8c22de0b463903de)) +* Use external pre-commit tool ([e9ef2ba](https://github.com/actuarysailor/template-readme-only/commit/e9ef2baeda72804fc1f4dd847fd116a69809d428)) +* Use generating tool ([fa65554](https://github.com/actuarysailor/template-readme-only/commit/fa65554f7a310134c77db434e2dd6dd4948790db)) + ## v1.1.2 -### Added or Changed +### Added or Changed (v1.1.2) + - Change license to Unlicense; releasing the project fully into the public domain - Add simplified project cover image - ## v1.1.1 -### Added or Changed -- Fixed back to top alignment (revert changes) +### Added or Changed (v1.1.1) +- Fixed back to top alignment (revert changes) ## v1.1.0 -### Added or Changed +### Added or Changed (v1.1.0) + - Fixed back to top link alignment deprecated tag, use CSS style instead - Added contrib.rocks to show top contributors - ## v1.0.0 -### Added or Changed +### Added or Changed (v1.0.0) + - Added this changelog :) - Fixed typos in both templates - Back to top links @@ -32,4 +59,4 @@ ### Removed -- Some packages/libraries from acknowledgements I no longer use \ No newline at end of file +- Some packages/libraries from acknowledgements I no longer use diff --git a/README.md b/README.md index b36d4fd4d..1197fc68a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ - - - - + + + +
+

Best-README-Template

+ + Logo + +
+ +
+ [![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![Unlicense License][license-shield]][license-url] -[![LinkedIn][linkedin-shield]][linkedin-url] - - +
+ - -
- - Logo - - -

Best-README-Template

-

An awesome README template to jumpstart your projects!
- Explore the docs ยป + + Explore the docs ยป +

- View Demo - · - Report Bug - · - Request Feature + + View Demo + + ยท + + Report Bug + + ยท + + Request Feature +

- - +
Table of Contents
    @@ -75,124 +83,151 @@
  1. License
  2. Contact
  3. Acknowledgments
    4. +
  4. FAQ
- - + ## About The Project [![Product Name Screen Shot][product-screenshot]](https://example.com) -There are many great README templates available on GitHub; however, I didn't find one that really suited my needs so I created this enhanced one. I want to create a README template so amazing that it'll be the last one you ever need -- I think this is it. +There are many great README templates available on GitHub; however, I didn't +find one that really suited my needs so I created this enhanced one. I want to +create a README template so amazing that it'll be the last one you ever need-- +I think this is it. -Here's why: -* Your time should be focused on creating something amazing. A project that solves a problem and helps others -* You shouldn't be doing the same tasks over and over like creating a README from scratch -* You should implement DRY principles to the rest of your life :smile: +Here's why: -Of course, no one template will serve all projects since your needs may be different. So I'll be adding more in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue. Thanks to all the people have contributed to expanding this template! +- Your time should be focused on creating something amazing. A project that +solves a problem and helps others +- You shouldn't be doing the same tasks over and over like creating a README +from scratch +- You should implement DRY principles to the rest of your life ๐Ÿ˜„ -Use the `BLANK_README.md` to get started. - -

(back to top)

+Of course, no one template will serve all projects since your needs may be +different. So I'll be adding more in the near future. You may also suggest +changes by forking this repo and creating a pull request or opening an issue. +Thanks to all the people have contributed to expanding this template! +Use the `BLANK_README.md` to get started. +

(back to top)

### Built With -This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples. +This section should list any major frameworks/libraries used to bootstrap your +project. Leave any add-ons/plugins for the acknowledgements section. Here are a +few examples. -* [![Next][Next.js]][Next-url] -* [![React][React.js]][React-url] -* [![Vue][Vue.js]][Vue-url] -* [![Angular][Angular.io]][Angular-url] -* [![Svelte][Svelte.dev]][Svelte-url] -* [![Laravel][Laravel.com]][Laravel-url] -* [![Bootstrap][Bootstrap.com]][Bootstrap-url] -* [![JQuery][JQuery.com]][JQuery-url] +- [![Next.js][Next.js.shield]][Next.js-url] +- [![React][React.shield]][React-url] +- [![Vue.js][Vue.js.shield]][Vue.js-url] +- [![Angular][Angular.shield]][Angular-url] +- [![Svelte][Svelte.shield]][Svelte-url] +- [![Laravel][Laravel.shield]][Laravel-url] +- [![Bootstrap][Bootstrap.shield]][Bootstrap-url] +- [![jQuery][jQuery.shield]][jQuery-url]

(back to top)

- - + ## Getting Started -This is an example of how you may give instructions on setting up your project locally. -To get a local copy up and running follow these simple example steps. +This is an example of how you may give instructions on setting up your project +locally. To get a local copy up and running follow these simple example steps. ### Prerequisites -This is an example of how to list things you need to use the software and how to install them. -* npm +This is an example of how to list things you need to use the software and how +to install them. + +- npm + ```sh npm install npm@latest -g ``` ### Installation -_Below is an example of how you can instruct your audience on installing and setting up your app. This template doesn't rely on any external dependencies or services._ +_Below is an example of how you can instruct your audience on installing and +setting up your app. This template doesn't rely on any external dependencies +or services._ + +1. Get a free API Key at https://example.com -1. Get a free API Key at [https://example.com](https://example.com) -2. Clone the repo ```sh - git clone https://github.com/github_username/repo_name.git + # Register at https://example.com + ``` + +2. Clone the repo + + ```bash + git clone https://github.com/your_username_/Project-Name.git ``` + 3. Install NPM packages - ```sh + + ```bash npm install ``` + 4. Enter your API in `config.js` - ```js + + ```sh const API_KEY = 'ENTER YOUR API'; ``` + 5. Change git remote url to avoid accidental pushes to base project - ```sh - git remote set-url origin github_username/repo_name - git remote -v # confirm the changes + + ```bash + git remote set-url origin https://github.com/your_username_/Project-Name.git ```

(back to top)

- - + ## Usage -Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. +Use this space to show useful examples of how a project can be used. Additional +screenshots, code examples and demos work well in this space. You may also link +to more resources. _For more examples, please refer to the [Documentation](https://example.com)_

(back to top)

- - + ## Roadmap - [x] Add Changelog - [x] Add back to top links -- [ ] Add Additional Templates w/ Examples -- [ ] Add "components" document to easily copy & paste sections of the readme +- [x] Add Additional Templates w/ Examples +- [x] Add "components" document to easily copy & paste sections of +the readme - [ ] Multi-language Support - - [ ] Chinese - - [ ] Spanish + - [ ] Chinese + - [ ] Spanish -See the [open issues](https://github.com/othneildrew/Best-README-Template/issues) for a full list of proposed features (and known issues). +See the [open issues](https://github.com/othneildrew/Best-README-Template/issues) +for a full list of proposed features (and known issues).

(back to top)

- - + ## Contributing -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. +Contributions are what make the open source community such an amazing place to +learn, inspire, and create. Any contributions you make are **greatly appreciated**. -If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". -Don't forget to give the project a star! Thanks again! +If you have a suggestion that would make this better, please fork the repo and +create a pull request. You can also simply open an issue with the tag +"enhancement". Don't forget to give the project a star! Thanks again! 1. Fork the Project 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) @@ -200,56 +235,61 @@ Don't forget to give the project a star! Thanks again! 4. Push to the Branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request -### Top contributors: +### Top contributors - contrib.rocks image + contrib.rocks image

(back to top)

- - + ## License Distributed under the Unlicense License. See `LICENSE.txt` for more information.

(back to top)

- - + ## Contact -Your Name - [@your_twitter](https://twitter.com/your_username) - email@example.com +| | | +|:---:|:---| +| Your Name | **Your Name** | +| ๐Ÿ“ง | [email@example.com](mailto:email@example.com) | +| ๐Ÿ™ | [@othneildrew](https://github.com/othneildrew) | +| ๐Ÿ’ผ | [LinkedIn](https://linkedin.com/in/othneildrew) | -Project Link: [https://github.com/your_username/repo_name](https://github.com/your_username/repo_name) +**Project Link:** [https://github.com/othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template)

(back to top)

- - + ## Acknowledgments -Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off! +Use this space to list resources you find helpful and would like to give credit +to. I've included a few of my favorites to kick things off! -* [Choose an Open Source License](https://choosealicense.com) -* [GitHub Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet) -* [Malven's Flexbox Cheatsheet](https://flexbox.malven.co/) -* [Malven's Grid Cheatsheet](https://grid.malven.co/) -* [Img Shields](https://shields.io) -* [GitHub Pages](https://pages.github.com) -* [Font Awesome](https://fontawesome.com) -* [React Icons](https://react-icons.github.io/react-icons/search) +- [Choose an Open Source License](https://choosealicense.com) +- [GitHub Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet) +- [Malven's Flexbox Cheatsheet](https://flexbox.malven.co/) +- [Malven's Grid Cheatsheet](https://grid.malven.co/) +- [Img Shields](https://shields.io) +- [GitHub Pages](https://pages.github.com) +- [Font Awesome](https://fontawesome.com) +- [React Icons](https://react-icons.github.io/react-icons/search)

(back to top)

- - + [contributors-shield]: https://img.shields.io/github/contributors/othneildrew/Best-README-Template.svg?style=for-the-badge [contributors-url]: https://github.com/othneildrew/Best-README-Template/graphs/contributors [forks-shield]: https://img.shields.io/github/forks/othneildrew/Best-README-Template.svg?style=for-the-badge @@ -260,22 +300,20 @@ Use this space to list resources you find helpful and would like to give credit [issues-url]: https://github.com/othneildrew/Best-README-Template/issues [license-shield]: https://img.shields.io/github/license/othneildrew/Best-README-Template.svg?style=for-the-badge [license-url]: https://github.com/othneildrew/Best-README-Template/blob/master/LICENSE.txt -[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555 -[linkedin-url]: https://linkedin.com/in/othneildrew [product-screenshot]: images/screenshot.png -[Next.js]: https://img.shields.io/badge/next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white -[Next-url]: https://nextjs.org/ -[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB +[Next.js.shield]: https://img.shields.io/badge/Next-black?style=for-the-badge&logo=next.js&logoColor=white +[Next.js-url]: https://nextjs.org/ +[React.shield]: https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB [React-url]: https://reactjs.org/ -[Vue.js]: https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vuedotjs&logoColor=4FC08D -[Vue-url]: https://vuejs.org/ -[Angular.io]: https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white +[Vue.js.shield]: https://img.shields.io/badge/vuejs-%2335495e.svg?style=for-the-badge&logo=vuedotjs&logoColor=%234FC08D +[Vue.js-url]: https://vuejs.org/ +[Angular.shield]: https://img.shields.io/badge/angular-%23DD0031.svg?style=for-the-badge&logo=angular&logoColor=white [Angular-url]: https://angular.io/ -[Svelte.dev]: https://img.shields.io/badge/Svelte-4A4A55?style=for-the-badge&logo=svelte&logoColor=FF3E00 +[Svelte.shield]: https://img.shields.io/badge/svelte-%23f1413d.svg?style=for-the-badge&logo=svelte&logoColor=white [Svelte-url]: https://svelte.dev/ -[Laravel.com]: https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white +[Laravel.shield]: https://img.shields.io/badge/laravel-%23FF2D20.svg?style=for-the-badge&logo=laravel&logoColor=white [Laravel-url]: https://laravel.com -[Bootstrap.com]: https://img.shields.io/badge/Bootstrap-563D7C?style=for-the-badge&logo=bootstrap&logoColor=white +[Bootstrap.shield]: https://img.shields.io/badge/bootstrap-%23563D7C.svg?style=for-the-badge&logo=bootstrap&logoColor=white [Bootstrap-url]: https://getbootstrap.com -[JQuery.com]: https://img.shields.io/badge/jQuery-0769AD?style=for-the-badge&logo=jquery&logoColor=white -[JQuery-url]: https://jquery.com +[jQuery.shield]: https://img.shields.io/badge/jquery-%230769AD.svg?style=for-the-badge&logo=jquery&logoColor=white +[jQuery-url]: https://jquery.com diff --git a/configs/example.json b/configs/example.json new file mode 100644 index 000000000..3a3eb13f6 --- /dev/null +++ b/configs/example.json @@ -0,0 +1,186 @@ +{ + "project": { + "title": "Best-README-Template", + "description": "An awesome README template to jumpstart your projects!", + "logo_path": "images/logo.png", + "screenshot_path": "images/screenshot.png" + }, + "repository": { + "github_username": "othneildrew", + "repo_name": "Best-README-Template", + "license": "Unlicense License", + "license_file": "LICENSE.txt" + }, + "contact": { + "name": "Your Name", + "email": "email@example.com", + "email_client": "example", + "socials": [ + { + "platform": "LinkedIn", + "username": "othneildrew", + "url": "https://linkedin.com/in/othneildrew", + "icon": "๐Ÿ’ผ", + "enabled": true + }, + { + "platform": "Twitter", + "username": "your_twitter", + "url": "https://twitter.com/your_twitter", + "icon": "๐Ÿฆ", + "enabled": false + } + ] + }, + "sections": { + "about": { + "enabled": true, + "content": "There are many great README templates available on GitHub; however, I didn't\nfind one that really suited my needs so I created this enhanced one. I want to\ncreate a README template so amazing that it'll be the last one you ever need--\nI think this is it.\n\nHere's why:\n\n- Your time should be focused on creating something amazing. A project that\nsolves a problem and helps others\n- You shouldn't be doing the same tasks over and over like creating a README\nfrom scratch\n- You should implement DRY principles to the rest of your life ๐Ÿ˜„\n\nOf course, no one template will serve all projects since your needs may be\ndifferent. So I'll be adding more in the near future. You may also suggest\nchanges by forking this repo and creating a pull request or opening an issue.\nThanks to all the people have contributed to expanding this template!\n\nUse the `BLANK_README.md` to get started." + }, + "built_with": { + "enabled": true, + "frameworks": [ + { + "name": "Next.js", + "url": "https://nextjs.org/", + "badge": "https://img.shields.io/badge/Next-black?style=for-the-badge&logo=next.js&logoColor=white" + }, + { + "name": "React", + "url": "https://reactjs.org/", + "badge": "https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB" + }, + { + "name": "Vue.js", + "url": "https://vuejs.org/", + "badge": "https://img.shields.io/badge/vuejs-%2335495e.svg?style=for-the-badge&logo=vuedotjs&logoColor=%234FC08D" + }, + { + "name": "Angular", + "url": "https://angular.io/", + "badge": "https://img.shields.io/badge/angular-%23DD0031.svg?style=for-the-badge&logo=angular&logoColor=white" + }, + { + "name": "Svelte", + "url": "https://svelte.dev/", + "badge": "https://img.shields.io/badge/svelte-%23f1413d.svg?style=for-the-badge&logo=svelte&logoColor=white" + }, + { + "name": "Laravel", + "url": "https://laravel.com", + "badge": "https://img.shields.io/badge/laravel-%23FF2D20.svg?style=for-the-badge&logo=laravel&logoColor=white" + }, + { + "name": "Bootstrap", + "url": "https://getbootstrap.com", + "badge": "https://img.shields.io/badge/bootstrap-%23563D7C.svg?style=for-the-badge&logo=bootstrap&logoColor=white" + }, + { + "name": "jQuery", + "url": "https://jquery.com", + "badge": "https://img.shields.io/badge/jquery-%230769AD.svg?style=for-the-badge&logo=jquery&logoColor=white" + } + ] + }, + "getting_started": { + "enabled": true, + "prerequisites": [ + { "name": "npm", "command": "npm install npm@latest -g" } + ], + "installation_steps": [ + { + "text": "Get a free API Key at https://example.com", + "command": "# Register at https://example.com" + }, + { + "text": "Clone the repo", + "command": "git clone https://github.com/your_username_/Project-Name.git", + "language": "bash" + }, + { + "text": "Install NPM packages", + "command": "npm install", + "language": "bash" + }, + { + "text": "Enter your API in `config.js`", + "command": "const API_KEY = 'ENTER YOUR API';" + }, + { + "text": "Change git remote url to avoid accidental pushes to base project", + "command": "git remote set-url origin https://github.com/your_username_/Project-Name.git", + "language": "bash" + } + ] + }, + "usage": { + "enabled": true, + "content": "Use this space to show useful examples of how a project can be used. Additional\nscreenshots, code examples and demos work well in this space. You may also link\nto more resources." + }, + "roadmap": { + "enabled": true, + "items": [ + { "text": "Add Changelog", "completed": true }, + { "text": "Add back to top links", "completed": true }, + { "text": "Add Additional Templates w/ Examples", "completed": true }, + { + "text": "Add \"components\" document to easily copy & paste sections of\nthe readme", + "completed": true + }, + { + "text": "Multi-language Support", + "completed": false, + "subitems": [ + { "text": "Chinese", "completed": false }, + { "text": "Spanish", "completed": false } + ] + } + ] + }, + "contributing": { + "enabled": true, + "show_contributors": true + }, + "license": { + "enabled": true + }, + "contact": { + "enabled": true + }, + "acknowledgments": { + "enabled": true, + "items": [ + { + "name": "Choose an Open Source License", + "url": "https://choosealicense.com" + }, + { + "name": "GitHub Emoji Cheat Sheet", + "url": "https://www.webpagefx.com/tools/emoji-cheat-sheet" + }, + { + "name": "Malven's Flexbox Cheatsheet", + "url": "https://flexbox.malven.co/" + }, + { + "name": "Malven's Grid Cheatsheet", + "url": "https://grid.malven.co/" + }, + { "name": "Img Shields", "url": "https://shields.io" }, + { "name": "GitHub Pages", "url": "https://pages.github.com" }, + { "name": "Font Awesome", "url": "https://fontawesome.com" }, + { + "name": "React Icons", + "url": "https://react-icons.github.io/react-icons/search" + } + ] + } + }, + "badges": { + "contributors": true, + "forks": true, + "stars": true, + "issues": true, + "license": true + } +} diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 000000000..4d90dad35 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,272 @@ +# Frequently Asked Questions (FAQ) + +## Getting Started + +### What is the purpose of this template, and how can I use it for my own project? + +This README template provides a professional, comprehensive structure for +documenting your projects. It includes: + +- **Clear project description** with logos and badges +- **Installation and usage instructions** +- **Contributing guidelines** to encourage community participation +- **Professional formatting** that works across different platforms + +To use it for your project: + +1. Use the `BLANK_README.md` file as your starting point +2. Search and replace placeholders with your actual information +3. Customize sections to fit your project's needs +4. Remove sections you don't need + +### How do I customize the template to fit my project's specific needs? + +The template is designed to be modular. Here's how to customize it: + +**Required customizations:** + +- `github_username` โ†’ your GitHub username +- `repo_name` โ†’ your repository name +- `project_title` โ†’ your project name +- `project_description` โ†’ brief description of your project +- `project_license` โ†’ your chosen license (e.g., MIT, Apache-2.0, etc.) +- `twitter_handle` โ†’ your Twitter/X handle +- `linkedin_username` โ†’ your LinkedIn username +- `email_client` โ†’ your email provider (e.g., gmail, outlook) +- `email` โ†’ your email address + +**Optional customizations:** + +- Remove sections you don't need (Built With, Roadmap, etc.) +- Add project-specific sections +- Customize the color scheme of badges +- Replace the logo with your own branding + +### How do I add more badges to my README? + +Badges are generated by [shields.io](https://shields.io). To add more badges: + +1. **Visit shields.io** and browse available badges +2. **Generate the badge URL** for your specific repository +3. **Add to the badges section** following this pattern: + +```markdown +[![Badge Name][badge-shield]][badge-url] + + +[badge-shield]: https://img.shields.io/badge/YOUR_BADGE_URL +[badge-url]: https://your-link-here +``` + +**Popular additional badges:** + +- Build status: `[![Build Status][build-shield]][build-url]` +- Code coverage: `[![Coverage][coverage-shield]][coverage-url]` +- Dependencies: `[![Dependencies][deps-shield]][deps-url]` +- Downloads: `[![Downloads][downloads-shield]][downloads-url]` +- Version: `[![Version][version-shield]][version-url]` + +### Can I add my translation to the repository? + +Yes! Translations are welcome and help make the template accessible to more +developers. Here are the ways to contribute translations: + +**For this template repository:** + +1. **Fork the repository** +2. **Create translated versions** of key files: + - `README.es.md` (Spanish) + - `README.fr.md` (French) + - `README.zh.md` (Chinese) + - `docs/FAQ.es.md` (translated FAQ) +3. **Translate section headers** and standard text +4. **Keep technical examples** in English or provide localized examples +5. **Submit a pull request** with your translation + +**For your own projects using this template:** + +1. **Create multiple README files** for different languages +2. **Link between translations** in each file +3. **Use consistent formatting** across all versions + +**Translation guidelines:** + +- Translate section headers and descriptive text +- Keep code examples and technical terms consistent +- Provide cultural context where appropriate +- Maintain the same structure and formatting + +### What's the difference between README.md and BLANK_README.md? + +- **README.md** - Example template showing what the final result looks like +- **BLANK_README.md** - Clean template with placeholders for you to customize + +### Do I need to keep both files? + +No! Use `BLANK_README.md` as your starting point, customize it, then rename it +to `README.md` for your project. You can delete the original files. + +## Customization + +### How do I add my own logo? + +1. Add your logo image to the `images/` folder +2. Update the logo reference in your README: + + ```markdown + Logo + ``` + +3. Update the `[product-screenshot]` reference at the bottom if needed + +### How do I customize the shields/badges? + +The shields are generated by [shields.io](https://shields.io). Update the URLs +at the bottom of the template: + +```markdown +[contributors-shield]: https://img.shields.io/github/contributors/YOUR_USERNAME/YOUR_REPO.svg?style=for-the-badge +``` + +Replace `YOUR_USERNAME` and `YOUR_REPO` with your actual GitHub username and +repository name. + +### Can I remove sections I don't need? + +Absolutely! The template is designed to be modular. Common sections to remove: + +- **Built With** - if not using frameworks +- **Roadmap** - for completed projects +- **LinkedIn badge** - if you prefer not to include social links +- **Table of Contents** - for simpler projects + +Just remember to also remove the corresponding links in the Table of Contents. + +### How do I add more sections? + +Follow the existing pattern: + +1. Add your section with proper markdown heading +2. Add a "back to top" link: + `

(back to top)

` +3. Update the Table of Contents with a link to your new section + +## Markdown & Formatting + +### Why are there HTML tags in a markdown file? + +Some features require HTML for proper formatting: + +- **Image sizing** - Markdown can't specify width/height +- **Center alignment** - Pure markdown doesn't support centering +- **Collapsible sections** - `
` and `` tags + +These are standard and supported by GitHub's markdown renderer. + +### Do I need the .markdownlint.json file? + +The `.markdownlint.json` file ensures your README follows markdown best +practices. It's optional but recommended for: + +- Consistent formatting +- Better readability +- Professional appearance +- Compatibility with markdown tools + +### How do I handle long URLs in markdown linting? + +The template uses "reference-style" links to keep the content readable: + +```markdown +[Link text][reference-name] + + +[reference-name]: https://very-long-url-here +``` + +This keeps the main content clean while satisfying line length requirements. + +## Technical Questions + +### Can I use this for commercial projects? + +Yes! This template is released under the Unlicense, meaning it's in the public +domain. You can use it for any purpose without attribution (though attribution +is appreciated). + +### Does this work with GitHub Pages? + +Yes! The template is fully compatible with GitHub Pages and will render +correctly. + +### How do I auto-generate README.md from BLANK_README.md? + +You can create scripts to: + +1. Read `BLANK_README.md` +2. Replace placeholders with actual values +3. Generate the final `README.md` + +This is useful for organizations with multiple repositories following the same +pattern. + +## Troubleshooting + +### My images aren't showing up + +Check these common issues: + +1. **File path** - Ensure `images/logo.png` exists in your repository +2. **Case sensitivity** - GitHub is case-sensitive (`Logo.png` โ‰  `logo.png`) +3. **File format** - Use common formats: PNG, JPG, GIF, SVG + +### The shields/badges show errors + +Common causes: + +1. **Repository not public** - Some shields require public repositories +2. **Incorrect username/repo** - Double-check your GitHub username and + repository name +3. **Repository too new** - Some metrics need time to populate + +### Markdown isn't rendering correctly + +1. **Check syntax** - Use a markdown linter or preview +2. **HTML compatibility** - Ensure HTML tags are properly closed +3. **Reference links** - Verify all `[reference]` links have corresponding + definitions + +## Contributing & Community + +### How can I improve this template? + +1. Fork the repository +2. Make your improvements +3. Submit a pull request with: + - Clear description of changes + - Examples of improvements + - Any relevant screenshots + +### I found a bug, what should I do? + +Please [open an issue](https://github.com/actuarysailor/template-readme-only/issues) +with: + +- Description of the problem +- Steps to reproduce +- Expected vs actual behavior +- Screenshots if applicable + +### How does this FAQ help reduce duplicate issues? + +This FAQ addresses the most common questions and concerns, which should: + +- **Reduce duplicate issues** by providing immediate answers +- **Save maintainer time** by directing users to existing solutions +- **Prevent conflicting pull requests** by clarifying design decisions +- **Improve user experience** by providing self-service support + +--- + +**Still have questions?** [Open an issue](https://github.com/actuarysailor/template-readme-only/issues) +and we'll help you out!