From af4bee0e4d7672ed0f9f33fdae8aea9671adda7c Mon Sep 17 00:00:00 2001 From: Jane Alesi Date: Mon, 2 Jun 2025 17:59:20 +0200 Subject: [PATCH] feat: Add comprehensive issue reporting and contribution guidelines (#105) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: Add issue reporting guidelines to README.md - Add dedicated "๐Ÿ› Issue Reporting" section with clear instructions - Direct users to main repository issue tracker - Include template for issue reporting with required information - Improve project transparency and user support workflow * fix: Update repository references and add issue reporting guidelines - Fix incorrect repository reference (satwareAG-ironMike โ†’ satwareAG) - Add comprehensive issue reporting section - Clarify workflow between forks and main repository - Improve contribution process documentation * feat: Add GitHub issue templates for better issue management - Add bug report template with structured fields - Provide clear guidance for issue reporting - Improve issue quality and processing efficiency * feat: Add feature request template - Add structured feature request template - Include sections for use case, implementation details, and alternatives - Improve feature planning and discussion process * feat: Add content issue template - Add template for content-related issues (typos, outdated info, etc.) - Provide specific fields for content corrections - Improve content quality maintenance process * feat: Add issue template configuration - Configure issue template chooser with clear options - Add contact links for support and security - Improve issue routing and user guidance * feat: Add pull request template - Add comprehensive PR template with structured sections - Include checklist for quality assurance - Improve code review and integration process --- .github/ISSUE_TEMPLATE/bug_report.yml | 107 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 ++ .github/ISSUE_TEMPLATE/content_issue.yml | 91 ++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 92 ++++++++++++++++ .github/pull_request_template.md | 93 ++++++++++++++++ CONTRIBUTING.md | 120 +++++++++++++++------ README.md | 19 +++- 7 files changed, 498 insertions(+), 35 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/content_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b75287f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,107 @@ +name: ๐Ÿ› Bug Report +description: Report a bug or unexpected behavior on satware.ai +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to report a bug! This helps us improve satware.ai for everyone. + + Before submitting, please search existing issues to avoid duplicates. + + - type: input + id: url + attributes: + label: Page URL + description: Where did you encounter this bug? + placeholder: https://satware.ai/path/to/page + validations: + required: true + + - type: textarea + id: bug-description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe what went wrong... + validations: + required: true + + - type: textarea + id: steps-to-reproduce + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. Scroll down to '...' + 4. See error + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe what should have happened... + validations: + required: true + + - type: dropdown + id: browser + attributes: + label: Browser + description: Which browser were you using? + options: + - Chrome + - Firefox + - Safari + - Edge + - Opera + - Other + validations: + required: true + + - type: input + id: browser-version + attributes: + label: Browser Version + description: What version of the browser were you using? + placeholder: e.g., Chrome 120, Safari 17.2 + + - type: dropdown + id: device-type + attributes: + label: Device Type + description: What type of device were you using? + options: + - Desktop + - Tablet + - Mobile + - Other + + - type: input + id: device-info + attributes: + label: Device Information + description: Operating system and version + placeholder: e.g., Windows 11, macOS 14.2, iOS 17, Android 14 + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context about the problem here, including screenshots if applicable. + placeholder: Any additional information that might help us understand the issue... + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our Code of Conduct + options: + - label: I agree to follow this project's Code of Conduct + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..cb700ba --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: ๐Ÿ“ง General Support + url: mailto:info@satware.ai + about: For general inquiries and support questions + - name: ๐Ÿ”’ Security Report + url: mailto:security@satware.ai + about: Report security vulnerabilities privately + - name: ๐Ÿ’ฌ Community Discussion + url: https://github.com/satwareAG/satware.ai/discussions + about: Ask questions and discuss ideas with the community \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/content_issue.yml b/.github/ISSUE_TEMPLATE/content_issue.yml new file mode 100644 index 0000000..8090dfe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/content_issue.yml @@ -0,0 +1,91 @@ +name: ๐Ÿ“ Content Issue +description: Report issues with website content (typos, outdated information, etc.) +title: "[Content]: " +labels: ["content", "needs-review"] +body: + - type: markdown + attributes: + value: | + Thank you for helping improve our content! Every correction makes satware.ai better. + + Before submitting, please search existing issues to avoid duplicates. + + - type: input + id: page-url + attributes: + label: Page URL + description: Which page has the content issue? + placeholder: https://satware.ai/path/to/page + validations: + required: true + + - type: dropdown + id: issue-type + attributes: + label: Content Issue Type + description: What type of content issue is this? + options: + - Typo/Grammar Error + - Outdated Information + - Broken Link + - Missing Information + - Incorrect Information + - Unclear/Confusing Content + - Translation Error + - Formatting Issue + - Other + validations: + required: true + + - type: textarea + id: current-content + attributes: + label: Current Content + description: Copy and paste the problematic content (if applicable) + placeholder: Paste the current content that needs correction... + + - type: textarea + id: suggested-correction + attributes: + label: Suggested Correction + description: How should the content be corrected? + placeholder: Provide your suggested correction... + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any additional context about the content issue + placeholder: | + - Why is this content incorrect/unclear? + - Do you have authoritative sources for the correction? + - Any other relevant details... + + - type: input + id: section-location + attributes: + label: Section/Location + description: Where on the page is this content located? + placeholder: e.g., "Introduction section", "Step 3 of the tutorial", "Footer links" + + - type: dropdown + id: severity + attributes: + label: Severity + description: How significant is this content issue? + options: + - Low - Minor typo or formatting + - Medium - Affects understanding + - High - Misleading or significantly outdated + - Critical - Factually incorrect or potentially harmful + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our Code of Conduct + options: + - label: I agree to follow this project's Code of Conduct + required: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..7418afe --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,92 @@ +name: โœจ Feature Request +description: Suggest a new feature or improvement for satware.ai +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a new feature! Your ideas help shape the future of satware.ai. + + Before submitting, please search existing issues to avoid duplicates. + + - type: textarea + id: feature-description + attributes: + label: Feature Description + description: A clear and concise description of the feature you'd like to see. + placeholder: Describe the feature you're requesting... + validations: + required: true + + - type: textarea + id: problem-statement + attributes: + label: Problem or Use Case + description: What problem does this feature solve? What use case does it address? + placeholder: | + As a [type of user], I want [what] so that [why]. + + Currently, I have to [current workaround] which is [problem with current approach]. + validations: + required: true + + - type: textarea + id: proposed-solution + attributes: + label: Proposed Solution + description: How would you like this feature to work? + placeholder: Describe your ideal solution... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Have you considered any alternative solutions or features? + placeholder: Describe any alternative solutions you've considered... + + - type: dropdown + id: feature-type + attributes: + label: Feature Type + description: What type of feature is this? + options: + - Content Addition + - User Interface Improvement + - Navigation Enhancement + - Performance Optimization + - Accessibility Improvement + - Mobile Experience + - Search Functionality + - Integration + - Documentation + - Other + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Low - Nice to have + - Medium - Would improve my experience + - High - Significant impact on usability + - Critical - Blocking my use of the site + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, mockups, or examples about the feature request here. + placeholder: Any additional information, examples, or mockups that might help us understand your request... + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our Code of Conduct + options: + - label: I agree to follow this project's Code of Conduct + required: true \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..ac05108 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,93 @@ +# Pull Request + +## ๐Ÿ“ Description + + + +**What does this PR do?** + +- [ ] Add new content +- [ ] Update existing content +- [ ] Fix bugs +- [ ] Improve styling/design +- [ ] Update documentation +- [ ] Other: _____ + +**Summary of changes:** + + +## ๐Ÿ”— Related Issues + + +- Relates to # +- Fixes # +- Closes # + +## ๐Ÿงช Testing + +**How has this been tested?** + +- [ ] Tested locally with `./mkdocs.sh` +- [ ] Tested in multiple browsers +- [ ] Tested on mobile/tablet +- [ ] Links verified +- [ ] All pages load correctly +- [ ] No broken functionality + +**Test environment:** +- OS: +- Browser(s): +- Device type: + +## ๐Ÿ“ธ Screenshots + + + +**Before:** + + +**After:** + + +## โœ… Checklist + +**Before submitting this PR:** + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] My code follows the project's style guidelines +- [ ] I have performed a self-review of my changes +- [ ] I have tested my changes locally +- [ ] I have checked that all links work correctly +- [ ] My changes generate no new warnings or errors +- [ ] I have added/updated documentation if needed +- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) + +**Content changes (if applicable):** + +- [ ] Content is accurate and up-to-date +- [ ] Spelling and grammar are correct +- [ ] Links are working and relevant +- [ ] Images have appropriate alt text +- [ ] Content follows the site's tone and style + +**Technical changes (if applicable):** + +- [ ] Code is properly formatted +- [ ] No hardcoded values where configuration should be used +- [ ] Changes are backward compatible +- [ ] Performance impact has been considered + +## ๐Ÿ’ฌ Additional Notes + + + +## ๐Ÿ“‹ Reviewer Checklist + + + +- [ ] Changes are properly tested +- [ ] Documentation is updated if needed +- [ ] No breaking changes introduced +- [ ] Security implications considered +- [ ] Performance impact acceptable +- [ ] Follows project conventions \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa4fe15..5786046 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,49 +2,101 @@ We welcome contributions to the `satware.ai` website! Your help is invaluable in making our documentation better. Please take a moment to review this document to understand how to contribute. +## ๐Ÿ› Issue Reporting + +**Before contributing code**, please check if there's an existing issue for your concern: + +**๐ŸŽฏ [Check & Report Issues Here](https://github.com/satwareAG/satware.ai/issues)** + +### When to Report an Issue + +- Found a bug or error on the website +- Have a feature request or suggestion +- Experiencing technical difficulties +- Notice inconsistencies in documentation + +### How to Report Issues + +When creating an issue, please include: + +1. **Clear, descriptive title** +2. **Detailed description** of the problem or request +3. **Steps to reproduce** (for bugs) +4. **Expected vs. actual behavior** +5. **Screenshots** (if applicable) +6. **Browser/device information** +7. **URL** where the issue occurs + +This helps our team address your concerns quickly and ensures no duplicate work. + ## How to Contribute -1. **Fork the Repository**: Start by forking the `satwareAG-ironMike/satware.ai` repository to your GitHub account. +### 1. Fork the Repository +Start by forking the `satwareAG/satware.ai` repository to your GitHub account. -2. **Clone Your Fork**: Clone your forked repository to your local machine: - ```bash - git clone https://github.com/YOUR_USERNAME/satware.ai.git - cd satware.ai - ``` +### 2. Clone Your Fork +Clone your forked repository to your local machine: +```bash +git clone https://github.com/YOUR_USERNAME/satware.ai.git +cd satware.ai +``` -3. **Create a New Branch**: Create a new branch for your feature or bug fix. Use a descriptive name (e.g., `feature/add-new-page`, `fix/broken-link`): - ```bash - git checkout -b feature/your-feature-name - ``` +### 3. Create a New Branch +Create a new branch for your feature or bug fix. Use a descriptive name (e.g., `feature/add-new-page`, `fix/broken-link`): +```bash +git checkout -b feature/your-feature-name +``` -4. **Set up Local Development**: Follow the "Local Development" instructions in the `README.md` to get the website running locally. - ```bash - ./mkdocs.sh - ``` - This will start a live-reloading server at `http://localhost:8000`. +### 4. Set up Local Development +Follow the "Local Development" instructions in the `README.md` to get the website running locally: +```bash +./mkdocs.sh +``` +This will start a live-reloading server at `http://localhost:8000`. -5. **Make Your Changes**: - * **Documentation**: Most content is written in Markdown files located in the `docs/` directory. - * **Styling**: Custom styles are defined in `overrides/assets/css/custom.scss`. Changes to this file will be automatically compiled to `docs/assets/css/custom.css` by the `scss_watcher.py` script running in your Docker container. - * **Configuration**: The main configuration is in `mkdocs.yml`. +### 5. Make Your Changes -6. **Test Your Changes**: Before submitting, ensure your changes work as expected by viewing them on your local development server. +- **Documentation**: Most content is written in Markdown files located in the `docs/` directory. +- **Styling**: Custom styles are defined in `overrides/assets/css/custom.scss`. Changes to this file will be automatically compiled to `docs/assets/css/custom.css` by the `scss_watcher.py` script running in your Docker container. +- **Configuration**: The main configuration is in `mkdocs.yml`. -7. **Commit Your Changes**: Write clear and concise commit messages. - ```bash - git add . - git commit -m "feat: Add new section on AI agents" - ``` - (Consider using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.) +### 6. Test Your Changes +Before submitting, ensure your changes work as expected by viewing them on your local development server. -8. **Push to Your Fork**: - ```bash - git push origin feature/your-feature-name - ``` +### 7. Commit Your Changes +Write clear and concise commit messages: +```bash +git add . +git commit -m "feat: Add new section on AI agents" +``` +(Consider using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.) -9. **Create a Pull Request**: Go to your forked repository on GitHub and create a new Pull Request targeting the `main-mkdocs` branch of the `satwareAG-ironMike/satware.ai` repository. - * Provide a clear title and description of your changes. - * Reference any related issues. +### 8. Push to Your Fork +```bash +git push origin feature/your-feature-name +``` + +### 9. Create a Pull Request +Go to your forked repository on GitHub and create a new Pull Request targeting the `main-mkdocs` branch of the `satwareAG/satware.ai` repository. + +- **Provide a clear title and description** of your changes +- **Reference any related issues** (e.g., "Fixes #123") +- **Explain the impact** of your changes +- **Include screenshots** for visual changes + +## Repository Workflow + +### Development Flow +1. **Issues** are created and discussed in the main repository: `satwareAG/satware.ai` +2. **Development** happens in individual forks +3. **Pull Requests** are submitted to the main repository +4. **Review and merge** happen in the main repository + +### Branch Strategy +- **Main branch**: `main-mkdocs` +- **Feature branches**: `feature/description` +- **Bug fix branches**: `fix/description` +- **Documentation branches**: `docs/description` ## Code of Conduct @@ -54,4 +106,4 @@ Please note that this project is released with a [Code of Conduct](CODE_OF_CONDU If you discover any security vulnerabilities, please report them responsibly by following our [Security Policy](SECURITY.md). -Thank you for contributing! +Thank you for contributing! \ No newline at end of file diff --git a/README.md b/README.md index 391a0c3..6f0461a 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,23 @@ The `satware.ai` website is automatically deployed to GitHub Pages. * **SCSS Changes Not Reflecting**: Ensure the `scss_watcher.py` is running correctly within your Docker container. Check the Docker logs for any errors during SCSS compilation. The `scss_watcher.py` monitors `overrides/assets/css/custom.scss` and compiles it to `docs/assets/css/custom.css`. * **Docker Issues**: If you encounter issues with the `./mkdocs.sh` script, verify that Docker is running and that you have the necessary permissions. +## ๐Ÿ› Issue Reporting + +Found a bug, have a feature request, or experiencing issues with the satware.ai website? Please report all issues to our main repository: + +**๐ŸŽฏ [Report Issues Here](https://github.com/satwareAG/satware.ai/issues)** + +When reporting issues, please include: + +- **Clear description** of the problem or feature request +- **Steps to reproduce** (if applicable) +- **Expected behavior** vs actual behavior +- **Browser/device information** (e.g., Chrome 120, Safari on iOS 17) +- **Screenshots or error messages** (if relevant) +- **URL** where the issue occurs (if specific to a page) + +This helps our team address your concerns quickly and effectively. We appreciate your feedback in making satware.ai better for everyone! + ## ๐Ÿค Contributing Contributions are welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. @@ -104,4 +121,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## ๐Ÿ“ง Contact -For any inquiries or support, please contact [info@satware.ai](mailto:info@satware.ai). +For any inquiries or support, please contact [info@satware.ai](mailto:info@satware.ai). \ No newline at end of file