Contributing to Blankie

There are many ways you can contribute, including:

• Testing & Bug Reports: Help test features and identify issues. Find a bug? Open an issue using our bug report template.
• Feature Suggestions: Have an idea for Blankie? Submit a feature request. Design mockups, UI/UX flows, and even rough sketches are welcome! Be sure to explain your use case and be open to discussion.
• Code Contributions: Dive right in and help us fix bugs, add new features, improve performance, and enhance Blankie's architecture.
• Documentation and Website Contributions: Help improve core documentation (like this page), write user guides and make changes or additions to the Blankie website.
• Other Ways: Interested in contributing in other ways? We're open to new ideas and suggestions, but please check the guidelines below.

Before You Start

• Code of Conduct: Please review our Code of Conduct. It ensures a safe and welcoming environment for everyone.
• Check Open / Existing Issues: Before starting on a new feature or bug fix, check other issues to make sure it hasn't already been addressed or reported. You may find a related issue with helpful discussion.
• Start with Small Steps: If you’re new to the project, it’s a good idea to begin with smaller tasks to get familiar with the code, contributing, and development processes.

If you'd like to help out with the source code, follow these guidelines:

1. Fork the Repository: Start by forking the Blankie repository to your GitHub account. You can then clone the forked repository to your local machine.
2. Set Up Your Development Configuration: Follow the development setup instructions to create a Configuration.xcconfig file with your own development team and bundle identifier (this file is ignored by git to keep your personal settings private). You may not use the same bundle identifier as the main Blankie app and you should not update these fields in configation of the project itself. Please keep your personal settings private.
3. Make the Changes: Write clean and clear code following Swift.org's guidelines. Use appropriate comments and match the existing code style and conventions in the project. Blankie uses swift-format with default settings to keep code clean and consistent. You can run it via XCode (Editor > Structure > Format File with ‘swift-format’) or command line to ensure consistent formatting. If you're unsure about style, feel free to ask in an issue or pull request.
   • Keep your changes focused and avoid unrelated changes in the same pull request. PRs that make unnecessary changes or are too large may be rejected or asked to be split into smaller PRs.
   • If you're adding new features, consider opening an issue first to discuss the feature and gather feedback before starting development.
4. Test: Ensure that your changes work correctly without causing issues in other areas. Blankie currently has a few basic unit tests that can be run in XCode to ensure core functions (initial state, sound playback, volume, reset) are performing as expected. You can write additional unit or even UI tests to make sure everything is working before checking in code.
5. Commit Your Changes: With each commit, write clear commit messages explaining the reason and context for your changes. This will help other collaborators understand the scope of your contributions.
6. Create a Pull Request: Submit a pull request from your branch with a clear explanation of the changes that you've made to the original project repository, along with the links to issues referenced (Closes #123, Fixes #345) .

Code Considerations

Before implementing changes that might alter core functionality in serious ways:

1. Discuss First

   • Open an issue to propose and discuss changes and gather feedback from maintainers and the community

2. Maintain Core Requirements

   • Maintain consistent volume normalization across all sounds
   • Ensure smooth transitions between sound states (play/pause/volume)
   • Preserve compatibility with macOS media controls
   • Protect functionality of existing user-saved presets

3. Implement Carefully

   • Prioritize backwards-compatible solutions
   • Develop migration paths for existing user settings
   • Document any breaking changes thoroughly in pull requests
   • Consider phased rollouts for major changes

Blankie aims to be accessible to users around the world, which means we need help translating the app into different languages. You don't need to be a programmer to contribute translations!

Getting Started with Translations

1. Check Current Status: Visit our translations page to see which languages already have translations and their status.

2. Get the Template: Download a English template or current translation in JSON or CSV format from the translations page with all the strings that need translation.

3. Edit the Template: Using any text editor, translate the English strings to your target language. Keep the structure intact - only modify the "target" content within the strings.

4. Submit Your Translation: There are two ways to submit translations:

   • GitHub Issue: Create a translation contribution issue and attach your JSON file
   • Email: Send updated translation files or general feedback to i18n@blankie.rest

Translation Guidelines

• Respect Context: The comment field provides context about where each string appears in the app. Use this to guide your translation choices.
• Consistency: Maintain consistent terminology throughout the translation.
• Special Characters: Pay attention to formatting placeholders like %@ (which represent variable content) and preserve them in your translation.
• Testing: If you have the ability to, you might also test your translations by building the app locally to see how they appear in context.

Translation Review Process

Once submitted, your translations will go through this process:

1. Initial review by the maintainers
2. For languages we can't verify internally, we may reach out to other community members who speak that language
3. After review, translations will be marked as either "translated" or "needs review"
4. Approved translations will be included in a future Blankie release

How to Submit Translations

You can submit translations in three ways:

1. GitHub Issue: Create a translation contribution issue and attach your updated JSON or CSV file

2. Email: Send your translation files to i18n@blankie.rest

3. Direct Import: If you're comfortable using a command line and XCode you can use our blanki18n tool to import your translations directly into the app. This is the preferred method for developers and contributors who want to test their translations locally.

   # Make the tool executable
   chmod +x blanki18n.swift
   
   # Using interactive mode (will prompt for language code)
   ./blanki18n.swift path/to/your-translation.[csv|json]
   
   # Or specify language code directly
   ./blanki18n.swift path/to/your-translation.[csv|json] es
   

   The tool will update Localizable.xcstrings directly with your translations for you to build and then test locally. You can then create a pull request with your changes on a fork.

For general translation feedback or to report issues with existing translations, you can create a GitHub issue or email us at the address above. If you have any other questions about translations or need clarification on specific strings, please don't hesitate to reach out. We're here to help!

It is important to give credit where credit is due. Contributors to Blankie may be credited on the Credits page of the Blankie website and on the app's About screen. If you would prefer not to be credited, please let us know in your pull request.

Blankie has a few core GitHub documentation pages that you can contribute to:

• Our README page
• Our CONTRIBUTING page

If you see a typo, error, or something that could be improved, feel free to submit a pull request with your changes. Also, if you have ideas for new documentation or sections, please open an issue to discuss your idea.

The rest of Blankie's documentation is made available via the Blankie website. The Blankie website code is located in the /docs directory. For technical details, and development setup, please refer to the website's README.

Before opening a pull request related to the website, please:

1. Review the website README
2. Follow the existing code style and organization
3. Test all changes locally
4. Test a production build using Google Lighthouse and ensure all Lighthouse scores remain at 100
   • You can do this by running npx astro build && npx astro preview from the /docs directory and then running Lighthouse tests in Chrome DevTools

The website serves as the main documentation hub for Blankie users, so clarity, accessibility, and performance are crucial. If you're unsure about any aspect of website development, feel free to open an issue for discussion.

At this time, we're not seeking new sound contributions to Blankie. However, if you have suggestions for sound effects, you are welcomed to post in the "What Sounds Would You Add to Blankie?" discussion thread.

There are undoubtedly other ways to contribute to Blankie that aren't covered above. If you have an idea for a new way to contribute, please open an issue to discuss it!

Blankie respects the rights of creators and the open source community, and we expect the same from our contributors. By contributing to Blankie, you agree that any contributions will be licensed under the same terms as Blankie itself. You also confirm that you have the right to license any code, content, or other materials you contribute. Contributors are expected to follow Blankie's License and Code of Conduct. Any contributions that violate these terms are subject to removal.

If you're unsure about the licensability of content you wish to contribute, please ask before submitting a PR. This includes:

• Sound files, images, or other media
• Code snippets from other projects
• AI generated content
• Third-party libraries and dependencies

As part of the open source community, we take licensing and attribution seriously. Proper licensing ensures that Blankie remains free and open while respecting the work of others.

If you have any questions or need clarification, open a new issue.

We appreciate your contributions, as they make Blankie better for everyone!