From f41f5fd01a10c49a68ecb4188d785eb7cdc669f0 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 31 Aug 2025 09:06:52 +0000 Subject: [PATCH 1/2] feat(docs): add nine new guides for open-source best practices This adds nine new comprehensive guides to the `/docs` directory, codifying best practices for creators using this template. The new guides cover a wide range of topics essential for modern open-source project management: - Versioning with SemVer and GitHub Releases - Community building - A project launch checklist - Secrets management with GitHub Actions - Workflow scheduling - Issue management and triage - Documentation best practices - Using GitHub Discussions - Maintainer security best practices --- docs/community-building-guide.md | 42 ++++++++++++++ docs/documentation-best-practices.md | 44 ++++++++++++++ docs/issue-management-guide.md | 63 ++++++++++++++++++++ docs/launch-checklist.md | 65 +++++++++++++++++++++ docs/secrets-management.md | 58 +++++++++++++++++++ docs/security-best-practices.md | 40 +++++++++++++ docs/using-github-discussions.md | 43 ++++++++++++++ docs/versioning-guide.md | 51 +++++++++++++++++ docs/workflow-scheduling.md | 86 ++++++++++++++++++++++++++++ 9 files changed, 492 insertions(+) create mode 100644 docs/community-building-guide.md create mode 100644 docs/documentation-best-practices.md create mode 100644 docs/issue-management-guide.md create mode 100644 docs/launch-checklist.md create mode 100644 docs/secrets-management.md create mode 100644 docs/security-best-practices.md create mode 100644 docs/using-github-discussions.md create mode 100644 docs/versioning-guide.md create mode 100644 docs/workflow-scheduling.md diff --git a/docs/community-building-guide.md b/docs/community-building-guide.md new file mode 100644 index 0000000..399c9d0 --- /dev/null +++ b/docs/community-building-guide.md @@ -0,0 +1,42 @@ +# Community Building Guide + +A thriving open-source project is built on a foundation of a healthy, welcoming, and effective community. Here are some best practices for fostering such an environment. + +## 1. Establish a Code of Conduct + +A [Code of Conduct](./CODE_OF_CONDUCT.md) is a document that outlines the expected standards of behavior for all community members. It's a clear statement that your project is a safe and inclusive space. + +- **Adopt a Standard:** You don't have to write one from scratch. The [Contributor Covenant](https://www.contributor-covenant.org/) is a widely used and respected choice. This repository includes a template to get you started. +- **Enforce It:** A Code of Conduct is only effective if it's enforced. Be prepared to act on reports of violations to protect your community. + +## 2. Be Welcoming and Responsive + +First impressions matter. How you treat newcomers will determine whether they stick around. + +- **Welcome Contributions:** Use a `CONTRIBUTING.md` file to explain how people can contribute. Thank contributors for their work, even if you don't merge it. +- **Be Responsive:** Respond to issues and pull requests in a timely manner. If you're busy, a quick "Thanks for the report, I'll look into this next week" is better than silence. + +## 3. Provide Clear Communication Channels + +Designate specific places for different types of community interaction. + +- **GitHub Issues:** Use issues for actionable tasks like bug reports and feature requests. This repository's [issue templates](./.github/ISSUE_TEMPLATE/) help structure this process. +- **GitHub Discussions:** Enable [GitHub Discussions](https://docs.github.com/en/discussions) for open-ended conversations, Q&A, and sharing ideas. This keeps your issue tracker focused. +- **Other Channels:** Consider a chat platform like Slack or Discord for more informal community interaction, but be mindful of the moderation overhead. + +## 4. Document Everything + +Good documentation is a cornerstone of a healthy community. It empowers users to solve their own problems and lowers the barrier to contribution. + +- **User Guides:** Write clear, concise guides for using your project. +- **Reference Material:** Provide detailed documentation for APIs, configuration options, and other technical aspects. +- **Contribution Guidelines:** Your `CONTRIBUTING.md` should clearly explain how to set up a development environment, run tests, and submit changes. + +## 5. Empower Your Community + +As your community grows, look for opportunities to empower trusted members. + +- **Recognize Contributors:** Acknowledge valuable contributions publicly. This could be through release notes, social media shout-outs, or a contributors list in your README. +- **Delegate Responsibility:** Invite experienced community members to help triage issues, review pull requests, or moderate discussion channels. + +Building a community takes time and effort, but it's one of the most rewarding aspects of maintaining an open-source project. By being intentional about creating a positive and productive environment, you can build a project that lasts. diff --git a/docs/documentation-best-practices.md b/docs/documentation-best-practices.md new file mode 100644 index 0000000..12e39b1 --- /dev/null +++ b/docs/documentation-best-practices.md @@ -0,0 +1,44 @@ +# Documentation Best Practices + +Good documentation is one of the most important aspects of a successful software project. It empowers users, reduces the support burden on maintainers, and encourages contributions. This guide covers the art of writing clear and effective documentation. + +## The Two Types of Documentation + +It's helpful to think of documentation in two main categories: user guides and reference material. A good project has both. + +### 1. User Guides (Tutorials) + +- **Purpose:** To teach a user how to accomplish a specific task. They are action-oriented. +- **Audience:** New users or users trying to solve a particular problem. +- **Format:** A step-by-step walkthrough. They tell a story. +- **Example:** A guide on "How to deploy this application to a server" or "How to build your first plugin." + +User guides are like a teacher showing a student how to do something. They should be easy to follow and focused on a practical outcome. + +### 2. Reference Material (The Dictionary) + +- **Purpose:** To provide a comprehensive, factual description of the system. It is information-oriented. +- **Audience:** Users who already have some familiarity with the project and need specific, detailed information. +- **Format:** Organized by topic, like a dictionary or an encyclopedia. +- **Example:** A complete list of all available API endpoints and their parameters, or a detailed description of every configuration option in a file. + +Reference material is like a technical manual. It should be accurate, exhaustive, and well-organized so that users can quickly find the exact information they need. + +## The Importance of Good Examples + +Code examples are the heart of good documentation. They bridge the gap between theory and practice. + +- **Make them practical:** Examples should demonstrate a real-world use case, not just the syntax of a function. +- **Make them copy-pasteable:** Ensure that examples can be copied and run directly without modification. This means including any necessary setup or import statements. +- **Keep them up-to-date:** There's nothing more frustrating than documentation with outdated examples. As your code evolves, make sure your examples do too. + +## Tips for Writing Good Docs + +1. **Know Your Audience:** Write for your users, not for yourself. Avoid jargon where possible, or explain it if it's necessary. +2. **Be Concise:** Get to the point. Users are often looking for a quick solution to a problem. +3. **Use a Clear Structure:** Use headings, lists, and code blocks to make your documentation easy to scan. +4. **Add Visuals:** Screenshots, diagrams, and GIFs can often explain a concept more effectively than text alone. +5. **Document the "Why":** Don't just explain _what_ something does; explain _why_ a user might want to use it. Provide context. +6. **Treat Docs like Code:** Documentation should be part of your development process. When you add a new feature or make a change, update the docs at the same time. Include documentation in your code review process. + +Writing documentation is a continuous process of refinement. By investing in clear, comprehensive, and user-focused documentation, you are investing in the long-term success of your project. diff --git a/docs/issue-management-guide.md b/docs/issue-management-guide.md new file mode 100644 index 0000000..b379902 --- /dev/null +++ b/docs/issue-management-guide.md @@ -0,0 +1,63 @@ +# Issue Management Guide + +Effective issue management is key to keeping your project organized and your community engaged. This guide covers best practices for using GitHub Issues, labels, and templates to triage bug reports and feature requests. + +## 1. Use Issue Templates + +The first step to effective issue management is to get clear, structured information from contributors. GitHub's issue templates are perfect for this. + +- **What they are:** Pre-populated templates for bug reports and feature requests that prompt the user for specific information. +- **Why they're useful:** They ensure you get the information you need to act on an issue, such as steps to reproduce a bug or the use case for a new feature. +- **How to use them:** This repository includes templates in the [`.github/ISSUE_TEMPLATE`](./.github/ISSUE_TEMPLATE) directory. You can customize them to fit your project's needs. + +## 2. Leverage Labels + +Labels are a powerful tool for categorizing and prioritizing issues. A good set of labels makes it easy to see the state of your project at a glance. + +### Recommended Label Categories + +- **Issue Type:** + - `bug`: A problem with the existing code. + - `feature-request`: A proposal for new functionality. + - `documentation`: An issue related to the docs. + - `maintenance`: Chores like refactoring or updating dependencies. + +- **Status:** + - `needs-triage`: A new issue that hasn't been reviewed yet. + - `confirmed`: A bug report that has been reproduced. + - `in-progress`: An issue that is actively being worked on. + - `blocked`: An issue that cannot be worked on due to external factors. + +- **Priority:** + - `critical`: Must be addressed immediately (e.g., a security vulnerability). + - `high`: Important and should be prioritized. + - `medium`: A standard issue. + - `low`: A non-urgent issue or nice-to-have feature. + +- **Contribution Welcome:** + - `good-first-issue`: A relatively simple issue that's a great entry point for new contributors. + - `help-wanted`: An issue that you'd like the community to help with. + +## 3. The Triage Workflow + +Triage is the process of reviewing new issues and preparing them for work. A typical workflow looks like this: + +1. **Review New Issues:** Regularly check for issues that don't have any labels or assignees. + +2. **Ensure Clarity:** If an issue is unclear, ask the author for more information. If they don't respond after a reasonable amount of time, it's okay to close the issue. + +3. **Reproduce Bugs:** For bug reports, try to reproduce the issue based on the information provided. If you can reproduce it, add a `confirmed` label. If not, ask for more details. + +4. **Apply Labels:** Add the appropriate `type`, `status`, and `priority` labels to the issue. + +5. **Engage with the Community:** + - For valid feature requests, discuss the proposal with the community to gauge interest and gather ideas. + - For issues you won't address, explain why and close the issue respectfully. + - For issues that are good for new contributors, add a `good-first-issue` label and perhaps a comment with pointers on how to get started. + +## 4. Use Milestones and Projects + +- **Milestones:** Group issues together for a specific release (e.g., `v1.1.0`). This helps you track progress towards your next version. +- **GitHub Projects:** For more complex work, use a project board to visualize and manage the workflow of issues and pull requests, similar to a Kanban board. + +By implementing these practices, you can create a clear, organized, and efficient issue management process that will benefit both you and your contributors. diff --git a/docs/launch-checklist.md b/docs/launch-checklist.md new file mode 100644 index 0000000..17918c0 --- /dev/null +++ b/docs/launch-checklist.md @@ -0,0 +1,65 @@ +# Project Launch Checklist + +Launching a new open-source project can be a daunting task. This checklist is designed to help you ensure a smooth and successful launch. + +## Pre-Launch + +This is the phase where you prepare your project for its public debut. + +### Code and Repository + +- [ ] Finalize initial feature set for `v1.0.0`. +- [ ] Write comprehensive tests and ensure they are all passing. +- [ ] Set up CI/CD workflows for testing and linting. +- [ ] Polish the codebase: remove commented-out code, fix typos, and ensure consistent styling. +- [ ] Run a security audit (e.g., check dependencies for known vulnerabilities). + +### Documentation + +- [ ] Write a clear and compelling `README.md`. +- [ ] Create a `CONTRIBUTING.md` file with guidelines for contributors. +- [ ] Add a `LICENSE` file (e.g., MIT, Apache 2.0). +- [ ] Write user guides and API reference documentation. +- [ ] Add a `CODE_OF_CONDUCT.md` to set community standards. + +### Community & Marketing + +- [ ] Prepare a blog post or announcement for the launch. +- [ ] Identify communities (e.g., Reddit, Hacker News, specific forums) where you will share your project. +- [ ] Create a project website or landing page (GitHub Pages is a great option). +- [ ] Set up social media accounts if desired. + +## Launch Day + +The day you make your project public. + +- [ ] **Publish your code:** Make your GitHub repository public. +- [ ] **Push the `v1.0.0` tag:** This will trigger your automated release workflow. + ```bash + git tag -a v1.0.0 -m "Initial public release" + git push origin main --tags + ``` +- [ ] **Publish your announcement:** Share your blog post and post on your chosen communities. +- [ ] **Monitor for feedback:** Keep a close eye on GitHub issues, social media, and other channels for questions and bug reports. +- [ ] **Be responsive:** Engage with early adopters, answer questions, and thank them for their interest. + +## Post-Launch + +The work doesn't stop after launch day. Now it's about building momentum. + +### Short-Term (First Week) + +- [ ] Triage and fix critical bugs reported by early users. +- [ ] Publish a `v1.0.1` patch release if necessary. +- [ ] Thank the community for the feedback and support. +- [ ] Share any positive press or comments. + +### Long-Term (First Month and Beyond) + +- [ ] Continue to be responsive to issues and pull requests. +- [ ] Start working on the features planned for `v1.1.0`. +- [ ] Nurture your community by empowering contributors (see the [Community Building Guide](./community-building-guide.md)). +- [ ] Set up a regular release cadence. +- [ ] Periodically review and update your documentation. + +This checklist is a starting point. Feel free to adapt it to the specific needs of your project. Good luck with your launch! diff --git a/docs/secrets-management.md b/docs/secrets-management.md new file mode 100644 index 0000000..ad6855b --- /dev/null +++ b/docs/secrets-management.md @@ -0,0 +1,58 @@ +# Secrets Management in GitHub Actions + +Properly managing secrets like API keys, access tokens, and other credentials is a critical aspect of security. This guide explains the best practice of using GitHub Actions secrets to handle sensitive information. + +## Why Secret Management is Important + +**Never commit secrets directly to your repository.** Once a secret is in your git history, it should be considered compromised, even if you later remove it from the current version of the code. A public repository is visible to everyone, and malicious actors actively scan for exposed credentials. + +Leaked secrets can lead to: + +- Unauthorized access to your accounts and services. +- Financial loss (e.g., if an API key for a paid service is stolen). +- Damage to your project's reputation. + +## Using GitHub Actions Secrets + +GitHub provides a secure way to store and use secrets within your repository for use in GitHub Actions workflows. + +### How it Works + +1. **Encrypted Storage:** Secrets are stored as encrypted values at the repository or organization level. +2. **Limited Access:** Secrets are only exposed to the specific GitHub Actions workflows you choose. They are not accessible to collaborators or even the repository owner once they are set. +3. **Redacted Logs:** GitHub automatically redacts secrets from workflow logs, preventing them from being accidentally exposed in build outputs. + +### How to Add a Repository Secret + +1. Navigate to your repository on GitHub. +2. Go to **Settings** > **Secrets and variables** > **Actions**. +3. Click the **New repository secret** button. +4. Enter a name for your secret (e.g., `NPM_TOKEN`, `AWS_ACCESS_KEY_ID`). This name will be used to reference the secret in your workflow files. +5. Paste the secret value into the **Value** field. +6. Click **Add secret**. + +![GitHub new secret page](https://docs.github.com/assets/cb-132240/images/help/settings/actions-secret-new-repo.png) + +### How to Use a Secret in a Workflow + +Once a secret is stored, you can access it in your workflow `.yml` files using the `secrets` context. + +Here's an example of a workflow step that uses a secret to publish a package to the npm registry: + +```yaml +- name: Publish to npm + uses: actions/setup-node@v3 + with: + node-version: "18" + registry-url: "https://registry.npmjs.org" +- run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} +``` + +In this example: + +- `secrets.NPM_TOKEN` refers to a repository secret named `NPM_TOKEN`. +- The secret's value is assigned to the `NODE_AUTH_TOKEN` environment variable, which is used by the `npm publish` command for authentication. + +By using GitHub Actions secrets, you can automate workflows that require access to sensitive information without compromising on security. It's a fundamental practice for any project that interacts with external services. diff --git a/docs/security-best-practices.md b/docs/security-best-practices.md new file mode 100644 index 0000000..69ecea1 --- /dev/null +++ b/docs/security-best-practices.md @@ -0,0 +1,40 @@ +# Security Best Practices for Maintainers + +As an open-source maintainer, you have a responsibility to ensure your project is secure. This guide covers some fundamental security practices to protect both your project and its users. + +## 1. Protect Your Accounts + +Your personal accounts are the first line of defense. If a malicious actor gains access to your GitHub account, they can do significant damage to your projects. + +- **Use a Strong, Unique Password:** Use a password manager to generate and store strong, unique passwords for every service you use. +- **Enable Two-Factor Authentication (2FA):** 2FA is the single most important thing you can do to secure your accounts. Enable it on your GitHub account, your email account, and your package manager accounts (e.g., npm). + +## 2. Manage Dependencies Securely + +Modern software projects rely heavily on third-party dependencies. A vulnerability in one of your dependencies is a vulnerability in your project. + +- **Enable Dependabot:** GitHub's Dependabot automatically scans your dependencies for known vulnerabilities and creates pull requests to update them to a secure version. This is enabled by default in this repository. +- **Review Dependencies:** When adding a new dependency, consider its popularity, maintenance status, and whether it has a good security track record. +- **Lock Your Dependencies:** Use a lock file (e.g., `package-lock.json`, `yarn.lock`) to ensure that you are using the exact same version of each dependency in every environment. + +## 3. Handle Security Reports Responsibly + +You need a clear process for how a security researcher can report a vulnerability to you privately. + +- **Create a `SECURITY.md` file:** This file, located in the `.github` directory, should explain how to report a security vulnerability. This repository includes a template [`SECURITY.md`](./.github/SECURITY.md) to get you started. +- **Use Private Vulnerability Reporting:** GitHub provides a feature for privately reporting vulnerabilities. This allows you to discuss and fix a vulnerability in a temporary private fork before it's announced to the public. +- **Be Responsive:** When you receive a security report, acknowledge it promptly. Keep the reporter informed of your progress. +- **Disclose Responsibly:** Once you have a fix, you should disclose the vulnerability. This typically involves: + - Publishing a security advisory. + - Releasing a new version with the fix. + - Requesting a CVE (Common Vulnerabilities and Exposures) identifier. + +## 4. Secure Your Workflows + +Your CI/CD workflows can be a target for attackers. + +- **Be Cautious with Third-Party Actions:** Only use GitHub Actions from trusted creators. Pin actions to a specific commit SHA rather than a branch name to prevent malicious code from being injected. +- **Limit Permissions:** Grant your workflows only the minimum permissions they need to do their job. +- **Manage Secrets:** Use [GitHub Actions secrets](./secrets-management.md) to store and use credentials. Never hardcode them in your workflow files. + +Security is an ongoing process, not a one-time checklist. By adopting these best practices, you can significantly improve the security posture of your open-source project and build trust with your users. diff --git a/docs/using-github-discussions.md b/docs/using-github-discussions.md new file mode 100644 index 0000000..90b707e --- /dev/null +++ b/docs/using-github-discussions.md @@ -0,0 +1,43 @@ +# Using GitHub Discussions + +GitHub Discussions is a feature designed to be the community forum for your project, right alongside your code. It provides a dedicated space for conversations, Q&A, and idea sharing, keeping your issue tracker clean and focused on actionable tasks. + +## Issues vs. Discussions: What's the Difference? + +Understanding when to use Issues and when to use Discussions is key to keeping your project organized. + +- **GitHub Issues** are for tracking specific, actionable tasks. They have a clear "done" state. + - **Use for:** Bug reports, feature requests with a clear scope, specific to-do items. + - **Example:** "The login button is broken on Safari." + +- **GitHub Discussions** are for open-ended conversations. They don't have a "done" state and are about exploration and communication. + - **Use for:** Q&A, sharing ideas, general feedback, showing off what you've built. + - **Example:** "What do you think about adding a dark mode?" or "How do I connect the app to a different database?" + +By directing non-actionable conversations to Discussions, you prevent your issue tracker from becoming cluttered with questions and long debates, allowing you to focus on the work that needs to be done. + +## How to Enable and Use Discussions + +1. **Enable Discussions:** In your repository settings, under the "Features" section, check the box for "Discussions." + +2. **Configure Categories:** Set up categories to organize your community's conversations. Good starting categories include: + - **Announcements:** For maintainers to share project news. + - **Q&A:** For users to ask questions. This category has a feature to mark an answer as correct. + - **Ideas:** For proposing and debating new features. + - **Show and Tell:** For community members to share what they've built with your project. + +![GitHub Discussions categories](https://docs.github.com/assets/cb-40234/images/help/discussions/categories-in-repo.png) + +## Best Practices for Maintainers + +1. **Seed the Conversation:** When you first enable Discussions, post a welcome message or an announcement to get things started. + +2. **Be Active:** Participate in discussions, answer questions, and encourage community members. Your engagement sets the tone. + +3. **Moderate as Needed:** As with any community forum, be prepared to moderate to ensure conversations remain respectful and productive, in line with your [Code of Conduct](./CODE_OF_CONDUCT.md). + +4. **Convert Issues to Discussions:** If a user opens an issue that is actually a question or a broad idea, you can convert it to a discussion. This moves the conversation to the right place while preserving the content. + +5. **Convert Discussions to Issues:** Conversely, if a discussion evolves into a concrete, actionable task (like a well-defined feature request), you can create an issue directly from the discussion to track the work. + +By embracing GitHub Discussions, you can foster a vibrant community, gather valuable feedback, and maintain a clean, organized workflow for managing your project's development. diff --git a/docs/versioning-guide.md b/docs/versioning-guide.md new file mode 100644 index 0000000..cdc02ef --- /dev/null +++ b/docs/versioning-guide.md @@ -0,0 +1,51 @@ +# Versioning and Release Management + +A well-defined versioning and release strategy is crucial for any professional software project. It provides clarity for consumers of your software and helps maintainers keep track of changes. This guide outlines best practices using Semantic Versioning (SemVer) and GitHub's automated release features. + +## Semantic Versioning (SemVer) + +Semantic Versioning is a widely adopted versioning scheme that gives meaning to version numbers. A version number is composed of three parts: `MAJOR.MINOR.PATCH`. + +- **MAJOR** version: Incremented for incompatible API changes. +- **MINOR** version: Incremented for adding functionality in a backward-compatible manner. +- **PATCH** version: Incremented for backward-compatible bug fixes. + +For example, `v1.2.3` means: + +- `1`: Major version 1 +- `2`: Minor version 2 +- `3`: Patch version 3 + +Adhering to SemVer helps users understand the impact of upgrading and allows them to specify dependency versions safely. + +### Pre-releases + +For versions that are not yet stable, you can use pre-release tags, such as `1.0.0-alpha.1`, `1.0.0-beta.2`, or `1.0.0-rc.1`. These are useful for testing and getting feedback before a final release. + +## Automated Releases with GitHub + +This repository is configured with a GitHub Actions workflow that automates the process of creating a GitHub Release when you push a new tag. + +### How it Works + +1. **Tag a Commit:** When your `main` branch is ready for a release, you create a git tag pointing to the commit you want to release. The tag name **must** follow Semantic Versioning (e.g., `v1.0.0`, `v2.3.1`). + + ```bash + git tag -a v1.0.0 -m "Initial release" + git push origin v1.0.0 + ``` + +2. **Workflow Trigger:** Pushing the tag to the repository triggers the [`release-on-tag.yml`](../../.github/workflows/release-on-tag.yml) workflow. + +3. **Automated Release Notes:** The workflow automatically generates release notes based on the titles of the pull requests merged since the last release. It categorizes them into sections like "Features," "Bug Fixes," and "Maintenance." + +4. **Create Release:** The workflow creates a new GitHub Release with the tag, the generated release notes, and any build artifacts you've configured. + +### Customizing Release Notes + +You can customize the title and body of the release notes by editing the following files: + +- [`/.github/RELEASE_TITLE.txt`](../../.github/RELEASE_TITLE.txt): A one-line title for your release. +- [`/.github/RELEASE_BODY.md`](../../.github/RELEASE_BODY.md): A markdown file where you can add introductory text or other custom content to the release notes. + +By combining Semantic Versioning with automated release workflows, you can maintain a professional, consistent, and low-friction release process for your project. diff --git a/docs/workflow-scheduling.md b/docs/workflow-scheduling.md new file mode 100644 index 0000000..2c8272d --- /dev/null +++ b/docs/workflow-scheduling.md @@ -0,0 +1,86 @@ +# Scheduling Workflows with Cron + +GitHub Actions allows you to automate tasks on a schedule, similar to the traditional cron utility in Unix-like systems. This is useful for recurring tasks like nightly builds, daily reports, or weekly dependency checks. + +## How it Works + +You can trigger a workflow to run at specific UTC times using the `schedule` event. This event is configured with a `cron` expression. + +```yaml +on: + schedule: + - cron: "30 5 * * 1-5" +``` + +This example triggers the workflow at 5:30 AM UTC every day from Monday to Friday. + +## Understanding Cron Syntax + +A cron expression is a string of five fields that represent a time schedule. + +``` +┌───────────── minute (0 - 59) +│ ┌───────────── hour (0 - 23) +│ │ ┌───────────── day of the month (1 - 31) +│ │ │ ┌───────────── month (1 - 12) +│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday) +│ │ │ │ │ +│ │ │ │ │ +* * * * * +``` + +### Special Characters + +- `*`: Matches any value. `* * * * *` runs every minute. +- `,`: Separates multiple values. `0,15,30,45 * * * *` runs at minutes 0, 15, 30, and 45. +- `-`: Defines a range of values. `0 9-17 * * *` runs every hour from 9 AM to 5 PM. +- `/`: Specifies a step value. `*/15 * * * *` runs every 15 minutes. + +### Examples + +| Cron Expression | Description | +| ----------------- | -------------------------------------------------- | +| `0 0 * * *` | Run at midnight UTC every day. | +| `0 9 * * 1` | Run at 9:00 AM UTC every Monday. | +| `0 * * * *` | Run at the beginning of every hour. | +| `*/30 9-17 * * *` | Run every 30 minutes between 9 AM and 5 PM UTC. | +| `0 0 1 * *` | Run at midnight UTC on the first day of the month. | + +## Example Workflow + +Here is a complete example of a workflow that runs a script every day at midnight UTC. + +```yaml +# .github/workflows/nightly-build.yml +name: Nightly Build + +on: + schedule: + - cron: "0 0 * * *" + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v3 + + - name: Run nightly script + run: ./scripts/run-nightly.sh +``` + +## Best Practices + +1. **Use UTC:** All scheduled times are in Coordinated Universal Time (UTC). Be sure to account for time zone differences. + +2. **Minimum Frequency:** The shortest interval you can schedule a workflow to run is every 5 minutes. + +3. **Use `workflow_dispatch`:** It's a good practice to add `workflow_dispatch` alongside `schedule`. This allows you to manually trigger the workflow from the GitHub UI, which is very useful for testing. + +4. **Be Mindful of Usage:** Scheduled workflows consume your GitHub Actions minutes. If a task doesn't need to run frequently, choose a longer interval. + +5. **Handle Failures:** Consider adding a step to your workflow to send a notification (e.g., via email or Slack) if a scheduled job fails. This way, you can quickly address any issues. + +By leveraging scheduled workflows, you can automate a wide range of maintenance and operational tasks, helping to keep your project healthy and up-to-date. From b2c5a5cc851c08572736f3b4d39397eeb5520b8f Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 31 Aug 2025 09:13:08 +0000 Subject: [PATCH 2/2] docs: add new guides to docs README --- docs/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/README.md b/docs/README.md index 2a869e1..0e05313 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,3 +19,12 @@ This directory contains the documentation for the `base` project. - **[Using Prettier](./prettier.md)**: A guide to installing and using Prettier for code formatting. - **[Repository Badges](./badges.md)**: An explanation of how to use and create repository badges. - **[Maintaining `base` as a Template Repository](./template-repo.md)**: A guide for maintainers of this template, outlining best practices and administrative steps. +- **[Versioning and Release Management](./versioning-guide.md)**: A guide to professional release management using Semantic Versioning and GitHub's automated release notes feature. +- **[Community Building Guide](./community-building-guide.md)**: Best-practice advice on how to foster a healthy, welcoming, and effective community around a new open-source project. +- **[Project Launch Checklist](./launch-checklist.md)**: A reusable checklist for ensuring a smooth and successful project launch. +- **[Secrets Management in GitHub Actions](./secrets-management.md)**: A guide on the best practice of using GitHub Actions secrets to manage sensitive credentials. +- **[Scheduling Workflows with Cron](./workflow-scheduling.md)**: A tutorial on how to use cron scheduling within GitHub Actions to automate recurring tasks. +- **[Issue Management Guide](./issue-management-guide.md)**: A guide to best practices for triaging bug reports and feature requests using GitHub Issues. +- **[Documentation Best Practices](./documentation-best-practices.md)**: A tutorial on the art of writing clear and effective documentation. +- **[Using GitHub Discussions](./using-github-discussions.md)**: A guide on how to leverage GitHub Discussions for community conversations. +- **[Security Best Practices for Maintainers](./security-best-practices.md)**: A guide covering basic security practices for open-source maintainers.