Deploy preview for PR 19 🛫

pr-preview/pr-19/README.md

@@ -0,0 +1,36 @@
+# RTS Development Guidelines
+
+A guide for promoting best practices among RTS code repositories.
+
+## Introduction
+
+The software industry is constantly evolving. Our own practices should similarly evolve to
+disseminate knowledge throughout teams, share ownership, make it easier for newcomers to start and
+for seasoned developers to contribute to any project.
+
+## Guides
+
+The following guides are offered to help you improve your repository:
+
+- [Readme Guide](./guides/README_GUIDE.md): Write a great introductory text for your repository.
+- [Contributing Guide](./guides/CONTRIBUTING_GUIDE.md): Ensure smooth collaboration and
+  contribution to your project.
+- [Code of Conduct Guide](./guides/CODE_OF_CONDUCT_GUIDE.md): Provide guidelines to ensure
+  everyone can safely contribute.
+- [License Guide](./guides/LICENSE_GUIDE.md): Pick an appropriate license.
+- [Security Guide](./guides/SECURITY_GUIDE.md): Provide guidelines for optimizing the security of
+  the repository and its content.
+
+> [!TIP]
+> GitHub Community Standards are a great source of information and best practices. You can check
+> that your project follows these standards at any time by checking _Community Standards_ under the
+_Insights_ section.
+
+More sources are available online for further reading; you can start exploring them
+at [opensource.guide](https://opensource.guide/).
+
+[open-issues]: https://github.com/SRGSSR/rts-development-guidelines/issues/new
+
+[submit-pr]: https://github.com/SRGSSR/rts-development-guidelines/compare
+
+[discussions]: https://github.com/SRGSSR/rts-development-guidelines/discussions

pr-preview/pr-19/_sidebar.md

@@ -0,0 +1,13 @@
+<!-- docs/_sidebar.md -->
+<img src="img/rts-logo.svg" alt="RTS" height="25"/> Development Guidelines
+* [Home](/)
+
+**Guides**
+
+* [Crafting a Readme](/guides/README_GUIDE.md)
+* [Understanding Licenses](/guides/LICENSE_GUIDE.md)
+* [Contributor's Handbook](/guides/CONTRIBUTING_GUIDE.md)
+* [Pull Request Manual](/guides/PULL_REQUEST_GUIDE.md)
+* [Code of Conduct Guidelines](/guides/CODE_OF_CONDUCT_GUIDE.md)
+* [Security policy Guidelines](/guides/SECURITY_GUIDE.md)
+* [Effective Commit Messaging](/guides/COMMIT_MESSAGE_GUIDE.md)

pr-preview/pr-19/guides/CODE_OF_CONDUCT_GUIDE.md

@@ -0,0 +1,20 @@
+# Code of Conduct Guide
+
+Promote a welcoming and safe environment for discussions and contributions.
+
+> [!TIP]
+> More information is available from [GitHub documentation][github-documentation].
+
+## Picking a Code of Conduct
+
+The [Contributor Covenant][contributor-covenant] provides a great Code of Conduct. You can use it
+as-is, adapt it to your needs, or write your own document.
+
+## Adding a Code of Conduct
+
+Add a file called `CODE_OF_CONDUCT.md` to the root of your repository, the `docs` folder, or
+the `.github` folder, with the text of the Code of Conduct you chose. GitHub automatically adds a
+link to this file in the _About_ section of your repository homepage.
+
+[github-documentation]: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project
+[contributor-covenant]: https://www.contributor-covenant.org/

pr-preview/pr-19/guides/COMMIT_MESSAGE_GUIDE.md

@@ -0,0 +1,80 @@
+# Effective Commit Messaging
+
+Clear and informative commit messages contribute significantly to a project's success. This guide
+outlines the importance of well-structured commit messages and descriptions.
+
+## Basic commit message structure
+
+A well-crafted commit message is structured to convey concise and actionable information about the
+changes made. It typically consists of a single-line summary and an optional extended description.
+
+### Summary line
+
+A good summary line is:
+
+- **Directive**: start with a concise imperative verb to indicate the action,
+  e.g.: `add`, `fix`, `update`.
+- **Specific**: it answers the question: What was done in this commit?
+- **Concise**: Keep it short and focused.
+
+Example: `add authentication integration`.
+
+### Description
+
+You can and should extend the commit message with a description. In the description you can
+reference issues, provide more detail and motivate your changes. Use bullet points for readability.
+
+Following the previous example:
+
+```
+Resolves #123 by securing access through authentication.
+
+- Implemented OAuth2 for secure user login
+- Implemented a custom login screen
+- Updated database schema to store user credentials securely
+```
+
+Here are some benefits of using commits descriptions:
+
+- **Motivate Choices**: Helps collaborators understand the reasoning behind specific decisions.
+- **Ease PR Creation**: Pre-populated the description of a pull request with the commit description.
+- **Archival Information**: Provides insight as a historical record when using inspection tools.
+- **Better collaboration**: A clean history makes it easier to understand and build upon previous
+  work.
+- **Traceability**: Tracing back changes allows developers to easily identify the introduction of
+  bugs or issues.
+
+## A case for conventional commits
+
+The [Conventional Commits specification][conventional-commits] provides a set of rules to simplify
+creating a clear commit history, making it easier to build automated tools on top of it. Some
+of the benefits of this approach:
+
+- **Automated Version Bumping**: Enable automated version bumping.
+- **Automated Release Notes**: Generate consistent release notes based on commit messages.
+- **Granular Filtering**: Facilitate filtering and navigation through commits based on their type.
+- **Enforceable**: Ensure adherence to the convention through a pre-commit hook.
+
+### Case of study
+
+Explore the commit histories of [pillarbox-web][pillarbox-web-history]
+and [pillarbox-web-demo][pillarbox-web-demo-history]. Both projects diligently adhere to the
+guidelines outlined in this article, incorporating conventional commits. A pre-commit hook is
+implemented in both cases to enforce adherence to the conventional commit format.
+
+For the former project, automated processes generate release notes and versions using semantic
+versioning. See the outcome for the [1.1.0 release of pillarbox-web][semver-release-example].
+
+## Conclusion
+
+Incorporating the practices outlined in this guide ensures that your commit messages and
+descriptions contribute positively to your project's development lifecycle. A well-documented commit
+history is a powerful collaboration tool.
+
+[conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/
+
+[pillarbox-web-history]: https://github.com/SRGSSR/pillarbox-web/commits/main/
+
+[pillarbox-web-demo-history]: https://github.com/SRGSSR/pillarbox-web-demo/commits/main/
+
+[semver-release-example]: https://github.com/SRGSSR/pillarbox-web/releases/tag/v1.1.0

pr-preview/pr-19/guides/CONTRIBUTING_GUIDE.md

@@ -0,0 +1,33 @@
+# Contributing Guide
+
+Provide more context about contributions you are looking for and how they should occur.
+
+> [!TIP]
+> More information is available from [GitHub documentation][github-documentation].
+
+## Writing Contributing guidelines
+
+Writing Contributing guidelines depends on your project and how your team decides to process
+contributions. To help you:
+
+- The [Pillarbox Contributing guidelines][pillarbox-contributing] is an example describing which
+  contributions are considered, how they should occur (with links to the corresponding templates)
+  and how they will be processed.
+- The following [template][contributing-template] can be used if you need to write Contributing
+  guidelines tailored to your needs.
+
+## Adding Contributing guidelines
+
+Add a file called `CONTRIBUTING.md` to the root of your repository, the `docs` folder, or
+the `.github` folder, with the text you wrote. GitHub automatically adds a link to this file in the
+_About_ section of your repository homepage.
+
+## Next steps
+
+Now that you've added a Contributing Guide to your project, you can help contributors further with
+a pull request template. Follow-up with our [Pull Request Manual][pr-guide].
+
+[github-documentation]: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
+[pillarbox-contributing]: https://github.com/SRGSSR/pillarbox-apple/blob/main/docs/CONTRIBUTING.md
+[contributing-template]: https://github.com/nayafia/contributing-template
+[pr-guide]: ./PULL_REQUEST_GUIDE

pr-preview/pr-19/guides/LICENSE_GUIDE.md

@@ -0,0 +1,33 @@
+# License Guide
+
+Make applicable license conditions transparent.
+
+> [!TIP]
+> More information is available from [GitHub documentation][github-documentation].
+
+## Choosing a license
+
+The following [online guide](https://choosealicense.com/) is an excellent way to pick a license.
+
+## Adding a license
+
+Add a file called `LICENSE` to the root of your repository, the `docs` folder, or the `.github`
+folder, with the text of the license you chose. GitHub automatically adds a link to this file in the
+_About_ section of your repository homepage.
+
+You can either repeat the license in each file requiring it but this is generally cumbersome. To
+make your life easier you can use the following reduced license instead, which points to the main
+license file for more information:
+
+```
+//
+//  Copyright (c) SRG SSR. All rights reserved.
+//
+//  License information is available from the LICENSE file.
+//
+```
+
+Avoid dates in license information since they have no real values and are likely never correctly
+updated.
+
+[github-documentation]: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository

pr-preview/pr-19/guides/PULL_REQUEST_GUIDE.md

@@ -0,0 +1,80 @@
+# Pull Request Manual
+
+Pull Requests are an integral aspect of a collaborative project. Through this process, contributors
+can propose modifications, enhancements, or new features to a codebase. **The true strength of a
+pull request lies in the subsequent peer review.**
+
+## Why Code Reviewing Matters
+
+- **Code Quality and Consistency:** Code reviewing ensures that the code adheres to established
+  standards, follows best practices, and maintains a high level of quality.
+- **Knowledge Sharing:** With code reviews, contributors can learn from each other's problem-solving
+  approaches, coding styles, promoting a culture of continuous learning within the team.
+- **Bug Prevention:** A fresh set of eyes often catches issues that the original author might have
+  overlooked.
+
+## The Pull Request Template
+
+The pull request template is a valuable tool for creating a successful pull request. It is a guide
+to help contributors understand what is expected of them.
+
+Here are some reasons why adding a pull request template to your repository is important:
+
+- **Clarity and Consistency**: A pull request template ensures that every contributor provides the
+  necessary information when proposing changes.
+- **Efficiency**: With a template, reviewers don't have to ask basic questions about the pull
+  request, as most of the essential details should be included in the template.
+- **Documentation**: Detailed pull requests serve as a form of documentation, providing insight into
+  the project's history and the rationale behind certain decisions.
+- **Quality Control**: A checklist in the template can serve as a reminder for contributors to
+  adhere to the project's standards and guidelines, leading to higher quality submissions.
+
+### Adding a Pull Request Template
+
+You can store your pull request template in `.github/pull_request_template.md`.
+You can review other options on the [GitHub documentation][github-creating-pr-template].
+
+### Example
+
+Here's an example of a pull request template; feel free to use it in your project and modify it to
+your needs:
+
+```markdown
+## Description
+
+> Please provide a brief summary of the changes made. Please explain why
+> this change was necessary. Was there a problem or an issue this change
+> will address? What will be improved with this change?
+
+## Changes Made
+
+> Please detail the modifications made. This could include areas such as
+> code, documentation, structure, or formatting.
+
+## Checklist
+
+- [ ] I have followed the project's style guidelines.
+- [ ] I have performed a self-review of my own changes.
+- [ ] I have made corresponding changes to the documentation.
+- [ ] My changes do not generate new warnings.
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] I have reviewed the contribution guidelines.
+```
+
+#### Creating a Checklist
+
+You can add a **Checklist** section to further guide contributors. In this section, add items that
+reflect the "Definition of Done" for your project or any specific guidelines mentioned in the
+"Contributing" section of the README. This could include items like:
+
+- My code follows the code style of this project.
+- I have added tests to cover my changes.
+- All new and existing tests passed.
+- My changes generate no new warnings.
+- I have updated the documentation accordingly.
+
+> [!Note]
+> Remember, the goal of the pull request template is to make collaboration easier by setting clear
+> expectations for contributions. Tailor it to suit the specific needs of your project.
+
+[github-creating-pr-template]: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

pr-preview/pr-19/guides/README_GUIDE.md

@@ -0,0 +1,96 @@
+# Crafting a Readme
+
+A well-structured and informative README is more than just documentation; it's a powerful tool for
+collaboration. Your README serves as the gateway for developers to understand and contribute to your
+project.
+
+## Why it Matters
+
+- **Reduces Barriers to Entry:** A clear and welcoming README lowers the learning curve, making it
+  easier for new contributors to understand the project and start contributing.
+- **Encourages Contribution:** By providing explicit guidelines on how to contribute, your README
+  becomes an invitation for developers to actively participate in the project.
+- **Fosters Transparency:** A well-crafted README sets the tone for open and transparent
+  communication.
+
+## The Template
+
+This template will assist you in creating a compelling and concise README for your project. It
+provides step-by-step guidance on introducing your project and providing essential information for
+setting up and running your application.
+
+> [!Tip]
+> Enhance your project's visual appeal with a representative image and badges.
+> Explore [Adding workflow badges][workflow-badges] for guidance. If your project is an application,
+> include production version links (e.g., app store links) and incorporate screenshots to showcase
+> its appearance.
+
+> [!Warning]
+> Avoid adding a table of contents unless it serves a specific purpose, as GitHub generates one
+> automatically.
+
+---
+
+```markdown
+# <Project Name>
+
+> Introduce your project with a clear overview of its goals, providing
+> essential context and addressing fundamental questions.
+
+## Quick Guide
+
+**Prerequisites and Requirements**
+
+> List any prerequisites or requirements needed before setting up the project.
+
+**Setup**
+
+> For application projects: provide instructions on running the application
+> locally.
+
+> For libraries, components, or frameworks: explain a typical setup, including
+> installation from a package distribution manager and a simple use case.
+> Avoid detailed development environment setup in this section.
+
+## Documentation
+
+> Include links to additional documentation resources related to your project in
+> this section.
+
+## Contributing
+
+> Clarify how others can contribute to the project, with guidelines for bug
+> reports, feature requests, or code contributions. Add a link to the Contribution
+> guidelines.
+
+> Describe any automated processes that facilitate smoother collaboration.
+> For instance, explain how to run linting tools. No need to justify conventions;
+> simply enumerate them.
+
+> For libraries, components, or frameworks, explain how to set up a local
+> environment for development. Avoid detailing this in the 'Quick Guide' section.
+
+## License
+
+> Provide a link to the License.
+
+## Acknowledgements
+
+> Give credit to third-party libraries, tools, or individuals whose work is used
+> or inspired your project.
+```
+
+---
+
+> [!Note]
+> Customize this template according to the specific needs of your projects. Add or remove sections
+> based on the nature of each project.
+
+
+[workflow-badges]: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge
+
+## Further Reading
+
+For more detailed information on specific topics not covered in this README, consider exploring the
+following articles: [Contributor's Handbook](./CONTRIBUTING_GUIDE.md)
+and [Understanding Licenses](./LICENSE_GUIDE.md).