diff --git a/pr-preview/pr-17/.nojekyll b/pr-preview/pr-17/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/pr-preview/pr-17/README.md b/pr-preview/pr-17/README.md new file mode 100644 index 0000000..c1e151a --- /dev/null +++ b/pr-preview/pr-17/README.md @@ -0,0 +1,34 @@ +# 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. + +> [!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 diff --git a/pr-preview/pr-17/_sidebar.md b/pr-preview/pr-17/_sidebar.md new file mode 100644 index 0000000..3f97a95 --- /dev/null +++ b/pr-preview/pr-17/_sidebar.md @@ -0,0 +1,11 @@ + +RTS 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) diff --git a/pr-preview/pr-17/guides/CODE_OF_CONDUCT_GUIDE.md b/pr-preview/pr-17/guides/CODE_OF_CONDUCT_GUIDE.md new file mode 100644 index 0000000..f43db1b --- /dev/null +++ b/pr-preview/pr-17/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/ diff --git a/pr-preview/pr-17/guides/CONTRIBUTING_GUIDE.md b/pr-preview/pr-17/guides/CONTRIBUTING_GUIDE.md new file mode 100644 index 0000000..19a7359 --- /dev/null +++ b/pr-preview/pr-17/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 diff --git a/pr-preview/pr-17/guides/LICENSE_GUIDE.md b/pr-preview/pr-17/guides/LICENSE_GUIDE.md new file mode 100644 index 0000000..b60a24f --- /dev/null +++ b/pr-preview/pr-17/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 diff --git a/pr-preview/pr-17/guides/PULL_REQUEST_GUIDE.md b/pr-preview/pr-17/guides/PULL_REQUEST_GUIDE.md new file mode 100644 index 0000000..f6e9593 --- /dev/null +++ b/pr-preview/pr-17/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 diff --git a/pr-preview/pr-17/guides/README_GUIDE.md b/pr-preview/pr-17/guides/README_GUIDE.md new file mode 100644 index 0000000..3d87236 --- /dev/null +++ b/pr-preview/pr-17/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 +# + +> 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). diff --git a/pr-preview/pr-17/img/rts-logo.svg b/pr-preview/pr-17/img/rts-logo.svg new file mode 100644 index 0000000..3c0a1ea --- /dev/null +++ b/pr-preview/pr-17/img/rts-logo.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + \ No newline at end of file diff --git a/pr-preview/pr-17/index.html b/pr-preview/pr-17/index.html new file mode 100644 index 0000000..ebaf42b --- /dev/null +++ b/pr-preview/pr-17/index.html @@ -0,0 +1,36 @@ + + + + + RTS Development Guidelines + + + + + + + + +
+ + + + + + +