Merge pull request #29 from attogram/add-docs-guides

feat(docs): add nine new guides for open-source best practices

Author: attogram

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.

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.

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.

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.

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!

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.