Skip to content

Commit ad2fa73

Browse files
CopilotUnited600
Copilot
and
United600
committed
Streamline documentation based on maintainer feedback
- Remove extra docs/README.md file - Move CONTRIBUTING.md to repository root - Simplify CONTRIBUTING.md by removing excessive information - Add emojis as requested - Remove ResX Resource Manager references - Update README.md links to reflect new structure Co-authored-by: United600 <[email protected]>
1 parent 3ae27d5 commit ad2fa73

File tree

4 files changed

+165
-546
lines changed

4 files changed

+165
-546
lines changed

‎CONTRIBUTING.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# 🎬 Contributing to Screenbox
2+
3+
Thank you for your interest in contributing to Screenbox! This guide will help you get started with developing and contributing to the project.
4+
5+
## 📋 Table of Contents
6+
7+
- [🚀 Getting Started](#-getting-started)
8+
- [⚙️ Development Environment Setup](#️-development-environment-setup)
9+
- [🏗️ Project Structure](#️-project-structure)
10+
- [🔄 Development Workflow](#-development-workflow)
11+
- [🧹 Code Guidelines](#-code-guidelines)
12+
- [🧪 Testing](#-testing)
13+
- [🌍 Translation](#-translation)
14+
- [📤 Submitting Contributions](#-submitting-contributions)
15+
16+
## 🚀 Getting Started
17+
18+
### Prerequisites
19+
20+
Before you begin, ensure you have the following installed:
21+
22+
- **Visual Studio 2022** (Community, Professional, or Enterprise) or later
23+
- Required workloads:
24+
- **WinUI application development**
25+
- Optional components (recommended):
26+
- **Universal Windows Platform tools**
27+
- **Windows 11 SDK (10.0.22621)**
28+
- **Windows 10** version 1903 (build 18362) or later, or **Windows 11**
29+
30+
> **Note**: JetBrains Rider should also work but specific setup instructions aren't covered in this guide.
31+
32+
## ⚙️ Development Environment Setup
33+
34+
### 1. Fork and Clone the Repository
35+
36+
1. **Fork the repository** on GitHub by clicking the "Fork" button
37+
2. **Clone your fork** to your local machine:
38+
```bash
39+
git clone https://github.com/YOUR_USERNAME/Screenbox.git
40+
cd Screenbox
41+
```
42+
43+
### 2. Open and Build the Solution
44+
45+
1. **Open the solution** in Visual Studio: `Screenbox.sln`
46+
2. **Build the solution** to restore NuGet packages: `Ctrl+Shift+B`
47+
3. **Set the platform** to x64 and **start debugging**: `F5`
48+
49+
Visual Studio's built-in Git integration should be sufficient for most development workflows.
50+
51+
## 🏗️ Project Structure
52+
53+
The solution contains two main projects:
54+
55+
```
56+
Screenbox.sln
57+
├── Screenbox/ # Main UWP application (UI layer)
58+
└── Screenbox.Core/ # Core business logic library
59+
```
60+
61+
### Key Architecture Patterns
62+
63+
- **MVVM (Model-View-ViewModel)**: Clean separation of UI and business logic
64+
- **Dependency Injection**: Services are injected for loose coupling
65+
- **Messaging**: Components communicate via the MVVM Toolkit messenger
66+
- **Services Architecture**: Business logic organized into focused services
67+
68+
### Main Directories
69+
70+
- `Screenbox/Views/`: XAML pages and user controls
71+
- `Screenbox/ViewModels/`: Presentation logic and data binding
72+
- `Screenbox.Core/Services/`: Business logic and data access
73+
- `Screenbox.Core/Models/`: Data structures and entities
74+
- `Screenbox/Strings/`: Localization resources
75+
76+
## 🔄 Development Workflow
77+
78+
### Creating a Pull Request
79+
80+
1. **Create a feature branch**: `git checkout -b feature/your-feature-name`
81+
2. **Make your changes** and commit them with descriptive messages
82+
3. **Push to your fork**: `git push origin feature/your-feature-name`
83+
4. **Open a pull request** on GitHub with a clear description
84+
85+
### Pull Request Guidelines
86+
87+
- Use descriptive titles that start with a prefix like `feat:`, `fix:`, or `docs:`
88+
- Include a clear description of what changes were made and why
89+
- Link to relevant issues if applicable
90+
## 🧹 Code Guidelines
91+
92+
### Code Formatting
93+
94+
Before committing changes, please:
95+
96+
1. **Run XAML Styler** on all `.xaml` files you've modified
97+
2. **Use Code Cleanup** (`Ctrl+K, Ctrl+E`) on all `.cs` files you've modified
98+
99+
### EditorConfig
100+
101+
The project includes a comprehensive `.editorconfig` file that defines formatting rules. Key highlights:
102+
103+
- **C# files**: 4-space indentation, UTF-8 with BOM encoding
104+
- **XAML files**: 4-space indentation, UTF-8 with BOM encoding
105+
- **Private fields**: Use underscore prefix (`_fieldName`)
106+
- **Async methods**: End with "Async" suffix
107+
- **Interfaces**: Start with "I" prefix
108+
109+
Your IDE should automatically apply these rules when the `.editorconfig` file is present.
110+
## 🧪 Testing
111+
112+
### Manual Testing Checklist
113+
114+
When testing your changes:
115+
116+
- ✅ **Functionality**: Verify your feature works as expected
117+
- ✅ **Performance**: Check that playback remains smooth
118+
- ✅ **Error handling**: Test edge cases and error scenarios
119+
- ✅ **Accessibility**: Test with different themes (light/dark/high contrast), screen scale, text scale factor, and gamepad navigation if possible
120+
- ✅ **UI**: Verify the interface looks correct and responsive
121+
122+
### Platform Testing
123+
124+
While not required, testing on different architectures (x64, x86, ARM64) is helpful if you have access to those systems.
125+
if (IsPlaying)
126+
{
127+
await _mediaService.PauseAsync();
128+
}
129+
else
130+
## 🌍 Translation
131+
132+
### Adding New Strings
133+
134+
When adding features that require new user-facing text:
135+
136+
1. **Only add new strings to the `.en-US.resw` files** in the `Screenbox/Strings/en-US/` directory
137+
2. **Use ReswPlus features** for pluralization and advanced formatting when needed
138+
3. **Follow existing naming conventions** for resource keys
139+
140+
The main resource files are:
141+
- `Resources.resw`: General UI strings
142+
- `KeyboardResources.resw`: Keyboard shortcuts and commands
143+
- `ManifestResources.resw`: App manifest strings
144+
145+
### Contributing Translations
146+
147+
For translating the app to other languages:
148+
- **Crowdin (Recommended)**: [crowdin.com/project/screenbox](https://crowdin.com/project/screenbox)
149+
- **Local translation**: Create copies of the `en-US` resource files in the appropriate language folder
150+
151+
## 📤 Submitting Contributions
152+
153+
1. **Ensure your code builds** without errors or warnings
154+
2. **Test your changes** thoroughly using the testing checklist above
155+
3. **Create a pull request** with a clear title and description
156+
4. **Be responsive** to feedback during the review process
157+
158+
That's it! The maintainers will review your contribution and provide feedback if needed.
159+
160+
## 🎉 Thank You!
161+
162+
Every contribution helps make Screenbox better for everyone. Whether you're fixing bugs, adding features, improving documentation, or translating the app, your efforts are appreciated! 🙏

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Feel free to open an issue if you want to report a bug, give feedback, or ask a
5656

5757
### For Contributors
5858

59-
- 📖 **[Contributing Guide](docs/CONTRIBUTING.md)** - Complete guide for new contributors
59+
- 📖 **[Contributing Guide](CONTRIBUTING.md)** - Complete guide for new contributors
6060
- 🏗️ **[Project Structure](docs/PROJECT_STRUCTURE.md)** - Detailed codebase architecture overview
6161

6262
### Quick Start for Developers
@@ -66,15 +66,15 @@ Feel free to open an issue if you want to report a bug, give feedback, or ask a
6666
3. **Build**: Open `Screenbox.sln` and build the solution (Ctrl+Shift+B)
6767
4. **Run**: Set platform to x64 and start debugging (F5)
6868

69-
See the [Contributing Guide](docs/CONTRIBUTING.md) for detailed setup instructions.
69+
See the [Contributing Guide](CONTRIBUTING.md) for detailed setup instructions.
7070

7171
## Translation
7272

7373
[![Crowdin](https://badges.crowdin.net/screenbox/localized.svg)](https://crowdin.com/project/screenbox)
7474

7575
Help translate the app to your language on [Crowdin](https://crowdin.com/project/screenbox)! Crowdin offers an intuitive UX for you to get started and is the recommended tool for localization. Translations are automatically synced to GitHub and published in the next minor update.
7676

77-
You can also translate the app locally without Crowdin. The project source language is English, United States. All localizable source files are in the `Screenbox\Strings\en-US` directory. Localizable file types are `.resw` and `.md`. It is recommended that you use [ResX Resource Manager](https://github.com/dotnet/ResXResourceManager) for easier `.resw` translation.
77+
You can also translate the app locally without Crowdin. The project source language is English, United States. All localizable source files are in the `Screenbox\Strings\en-US` directory. Localizable file types are `.resw` and `.md`.
7878

7979
Make sure you have your translations in the appropriate folder under the `Screenbox\Strings` directory. We use a [IETF language tag](https://www.venea.net/web/culture_code) to name the folder that contains resources for that language (e.g. `fr-FR` for French (France), `es-ES` for Spanish (Spain)). Files in these folders are translated copies of the original resource files in `Screenbox\Strings\en-US`.
8080

0 commit comments

Comments
 (0)