mw/satware.ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add comprehensive issue reporting and contribution guidelines (#105)

Browse Source 
* 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
This commit is contained in:
ja
2025-06-02 17:59:20 +02:00
committed by GitHub
parent faf199aca7
commit af4bee0e4d
7 changed files with 498 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.yml
+107
View File
@@ -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
.github/ISSUE_TEMPLATE/config.yml
+11
View File
@@ -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
.github/ISSUE_TEMPLATE/content_issue.yml
+91
View File
@@ -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
.github/ISSUE_TEMPLATE/feature_request.yml
+92
View File
@@ -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
.github/pull_request_template.md
+93
View File
@@ -0,0 +1,93 @@
# Pull Request
## 📝 Description
<!-- Provide a brief description of the changes in this PR -->
**What does this PR do?**
- [ ] Add new content
- [ ] Update existing content
- [ ] Fix bugs
- [ ] Improve styling/design
- [ ] Update documentation
- [ ] Other: _____
**Summary of changes:**
<!-- Describe what you've changed/added/fixed -->
## 🔗 Related Issues
<!-- Link any related issues. Use "Fixes #123" to automatically close issues when PR is merged -->
- 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
<!-- If applicable, add screenshots to help explain your changes -->
**Before:**
<!-- Screenshot of the current state (if applicable) -->
**After:**
<!-- Screenshot of your changes -->
## ✅ 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
<!-- Add any additional context, concerns, or notes for reviewers -->
## 📋 Reviewer Checklist
<!-- For maintainers reviewing this PR -->
- [ ] Changes are properly tested
- [ ] Documentation is updated if needed
- [ ] No breaking changes introduced
- [ ] Security implications considered
- [ ] Performance impact acceptable
- [ ] Follows project conventions
CONTRIBUTING.md
+66 -14
View File
@@ -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:
### 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`):
### 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.
### 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.
### 6. Test Your Changes
Before submitting, ensure your changes work as expected by viewing them on your local development server.
### 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.)
8. **Push to Your Fork**:
### 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-ironMike/satware.ai` repository.
* Provide a clear title and description of your changes.
* Reference any related issues.
### 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
README.md
+17
View File
@@ -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.