feat: Contributors guidelines updated

en/contributors/contribution-workflow/github-pull-request-guidelines.md

@@ -96,33 +96,4 @@ Example of a generated PR titles. Note the different prefixes for generic and St
 
 ### Squashing
 
-When merging a pull request, the Stride team might squash the commits into a single commit. This is to keep the git history clean and to make it easier to understand the changes that were made in the future.
-
-## Documentation
-
-Contributing to Stride not only involves code changes but also requires keeping the [documentation](https://doc.stride3d.net/latest/en/index.html), including the [API Docs](https://doc.stride3d.net/latest/en/api/index.html) and [Manual](https://doc.stride3d.net/latest/en/manual/index.html), current and comprehensive.
-
-### Enforcing Documentation Updates
-
-The Stride team prioritizes documentation as part of the PR review process to maintain the accuracy and completeness of information. Ensuring documentation updates with every change helps users and contributors alike understand and utilize Stride's features effectively.
-
-### API Documentation
-
-For the benefit of both IDE users and those utilizing the generated API Docs, it's crucial that any `public` interfaces, classes, methods, properties in C# are thoroughly documented with [XML comments](https://dotnet.github.io/docfx/docs/basic-concepts.html). This practice allows users to receive contextual information within their IDEs and aids in generating comprehensive API documentation.
-
-**Key Points for API Documentation:**
-
-- **XML Comments:** All `public` members intended for use should include descriptive XML comments. These comments are integral to generating useful API documentation and provide essential guidance directly in the IDE.
-- **Descriptive Information:** Comments should clearly describe the purpose, parameters, return values, and any exceptions thrown by the method or property. This information is invaluable for developers integrating these features into their projects.
-- **Use `<remarks></remarks>`:** For additional context or usage examples, the `<remarks>` tag can be used within XML comments to provide supplementary information. This can enhance understanding and demonstrate practical applications of API elements.
-
-### Updating the Manual
-Significant changes, such as the introduction of new features or modifications to existing ones, necessitate updates to the Stride user manual. It's essential that these updates accurately reflect the changes to provide users with the latest information on utilizing Stride's capabilities.
-
-It's up to the Stride team, alongside our amazing contributors, to make sure that any new contributions bring along updates to the manual. This teamwork between the contributors and our review team helps keep our documentation a rich and invaluable resource for everyone in our community.
-
-### ReleaseNotesNext.md
-
-The [ReleaseNotesNext.md](https://doc.stride3d.net/latest/en/ReleaseNotes/ReleaseNotesNext.html) file is a crucial document that should be continuously updated with summaries of important/major PRs that have been merged and are noteworthy for the community, such as new features.
-
-This document serves as a running log of all significant changes slated for inclusion in the next release. Keeping this document current is vital for ensuring that the release notes are both accurate and exhaustive, thereby **streamlining the release process**.
+When merging a pull request, the Stride team might squash the commits into a single commit. This is to keep the git history clean and to make it easier to understand the changes that were made in the future.

en/contributors/contribution-workflow/index.md

@@ -18,14 +18,17 @@ graph TB
     B[Create Branch 'X']
     C[Make Updates on Branch 'X']
     D{Has the Upstream Changed?}
-    E[Sync/Merge Upstream to Forked Main Branch]
-    F[Sync/Merge Forked Main Branch to Branch 'X']
-    G[Test your updates]
+    E[Sync/Merge Upstream with Forked Main Branch]
+    F[Sync/Merge Forked Main Branch with Branch 'X']
+    G[Test Your Updates]
     H["Create a Pull Request (PR)"]
-    I[Address PR Feedback]
-    J[Wait for the PR to be Merged]
-    K[Sync/Merge Upstream to Your Forked Main Branch]
-    L{Do You Want to Make More Updates?}
+    I[Maintainers Review]
+    J[Address PR Feedback]
+    K[Revise and Update PR as Necessary]
+    L[Wait for PR to be Merged by Maintainers]
+    M[Sync/Merge Upstream with Your Forked Main Branch]
+    N[Update or Add relevant Documentation]
+    O{Additional Contributions?}
     Z[End]
 
 %% Edges
@@ -33,19 +36,29 @@ graph TB
     D -->|Yes| E
     D -->|No| G
     E --> F --> G
-    G --> H --> I --> J --> K --> L
-    L -->|Yes| B
-    L -->|No| Z
+    G --> H --> I --> J --> K --> L --> M --> N --> O
+    O -->|Yes| B
+    O -->|No| Z
 ```
 
 ## Detailed Steps
 
-1. **Fork the Repository**: Start by forking the repository of the project you wish to contribute to
-1. **Create a Branch**: Name your branch appropriately and start making your changes
-1. **Make and Test Updates**: Implement your changes and test them within your branch
-1. **Review and Create a PR**: Review your updates and create a Pull Request to the main repository
-1. **Address Feedback**: If there is any feedback on your PR, address it to improve your contribution
-1. **Final Merging**: Once your PR is approved, it will be merged into the main project
+1. **Fork the Repository**: Begin by forking the repository of the project you're interested in contributing to. This creates a personal copy for you to work on.
+1. **Create a Branch 'X'**: Create a new branch in your forked repository, naming it appropriately for the changes you plan to implement.
+1. **Make Updates on Branch 'X'**: Implement your changes within this new branch. Ensure your modifications align with the project's standards and guidelines.
+1. **Has the Upstream Changed?**: Regularly check if the original repository has been updated. Keeping your fork in sync with the upstream ensures compatibility and reduces conflicts.
+1. **Sync/Merge Upstream with Forked Main Branch**: If the upstream has changed, update your forked repository's main branch to reflect the latest changes from the original project.
+1. **Sync/Merge Forked Main Branch with Branch 'X'**: Ensure your working branch 'X' is also updated with any new changes from the main branch of your fork.
+1. **Test Your Updates**: Thoroughly test your updates to confirm they work as expected and do not introduce new issues.
+1. **Create a Pull Request (PR)**: Once satisfied with your changes and testing, submit a pull request to the original repository for review.
+1. **Maintainers Review**: The project maintainers will review your PR. This process ensures that contributions are beneficial and fit the project's goals.
+1. **Address PR Feedback**: If maintainers or other contributors have feedback, make the necessary adjustments to your PR. This collaborative effort enhances the project's quality.
+1. **Revise and Update PR as Necessary**: Continue to refine and update your PR based on ongoing feedback until it meets the project's standards for merging.
+1. **Wait for PR to be Merged by Maintainers**: After approval, maintainers will merge your PR into the project. This step integrates your contribution with the main codebase.
+1. **Sync/Merge Upstream with Your Forked Main Branch**: Post-merge, ensure your forked repository's main branch is updated to include your newly merged changes.
+1. **Update or Add Relevant Documentation**: Contribute to the project's documentation to reflect your changes, helping future users and contributors understand the new functionalities or fixes.
+1. **Additional Contributions?**: Consider whether you want to make further contributions. If so, start the process again by creating a new branch.
+1. **End**: Conclude your current contribution cycle. Whether you decide to contribute more or take a break, your efforts have now been integrated into the project.
 
 ## Best Practices
 1. Ensure your updates align with the project goals and guidelines

en/contributors/contribution-workflow/xml-comments-and-docs.md

@@ -0,0 +1,28 @@
+# XML Comments and Docs
+
+Contributing to Stride not only involves code changes but also requires keeping the [documentation](https://doc.stride3d.net/latest/en/index.html), including the [API Docs](https://doc.stride3d.net/latest/en/api/index.html) and [Manual](https://doc.stride3d.net/latest/en/manual/index.html), current and comprehensive.
+
+## Enforcing Documentation Updates
+
+The Stride team prioritizes documentation as part of the PR review process to maintain the accuracy and completeness of information. Ensuring documentation updates with every change helps users and contributors alike understand and utilize Stride's features effectively.
+
+## API Documentation
+
+For the benefit of both IDE users and those utilizing the generated API Docs, it's crucial that any `public` interfaces, classes, methods, properties in C# are thoroughly documented with [XML comments](https://dotnet.github.io/docfx/docs/basic-concepts.html). This practice allows users to receive contextual information within their IDEs and aids in generating comprehensive API documentation.
+
+**Key Points for API Documentation:**
+
+- **XML Comments:** All `public` members intended for use should include descriptive XML comments. These comments are integral to generating useful API documentation and provide essential guidance directly in the IDE.
+- **Descriptive Information:** Comments should clearly describe the purpose, parameters, return values, and any exceptions thrown by the method or property. This information is invaluable for developers integrating these features into their projects.
+- **Use `<remarks></remarks>`:** For additional context or usage examples, the `<remarks>` tag can be used within XML comments to provide supplementary information. This can enhance understanding and demonstrate practical applications of API elements.
+
+## Updating the Manual
+Significant changes, such as the introduction of new features or modifications to existing ones, necessitate updates to the Stride user manual. It's essential that these updates accurately reflect the changes to provide users with the latest information on utilizing Stride's capabilities.
+
+It's up to the Stride team, alongside our amazing contributors, to make sure that any new contributions bring along updates to the manual. This teamwork between the contributors and our review team helps keep our documentation a rich and invaluable resource for everyone in our community.
+
+## ReleaseNotesNext.md
+
+The [ReleaseNotesNext.md](https://doc.stride3d.net/latest/en/ReleaseNotes/ReleaseNotesNext.html) file is a crucial document that should be continuously updated with summaries of important/major PRs that have been merged and are noteworthy for the community, such as new features.
+
+This document serves as a running log of all significant changes slated for inclusion in the next release. Keeping this document current is vital for ensuring that the release notes are both accurate and exhaustive, thereby **streamlining the release process**.