final review for github good practices

Author: imohitmayank

docs/data_science_tools/github_good_practices.md

@@ -3,20 +3,18 @@ Github Good Practices
 
 ## Introduction
 
-[GitHub](https://github.com/) is a powerful tool for version control and collaboration. By following these best practices, we can optimize our workflow, improve code quality, and enhance your team's productivity.
+[GitHub](https://github.com/) is a powerful tool for version control and collaboration. In this guide, we will cover essential practices for using GitHub effectively. Whether you are a beginner or an experienced developer, adhering to these practices will help you and your team work more efficiently and maintain a high standard of code quality.
 
-In this guide, we will cover essential practices for using GitHub effectively. Whether you are a beginner or an experienced developer, adhering to these practices will help you and your team work more efficiently and maintain a high standard of code quality.
-
-## Individual Practices
+## Practices
 
 Let's go through individual steps in the lifecycle of using Github to discuss good practices,
 
 ### Repositories
 
-- **Creating Repo:** Create a new repository when starting a new project, developing a standalone feature, or creating a reusable component. That said, we should be careful about not creating separate projects if the individual modules are supposed to be used together. For example, if we are creating a dashboard (say, using React) that requires specific endpoints (say, using Python), we can combine the into a single repo and run both applications.
+- **Creating Repo:** Create a new repository when starting a new project, developing a standalone feature, or creating a reusable component. That said, we should be careful about not creating separate projects if the individual modules are supposed to be used together. For example, if we are creating a dashboard *(say, using React)* that requires specific endpoints *(say, using Python)*, we can combine the into a single repo and run both applications.
 - **Project Owner**: Each repo should have at least one Spock or owner who is responsible for new implementation or reviewing any changes made by others in form of PR. This helps with concentrating ownership and responsibility. 
-- **Repo Structure:** The organization of files and directories within a repository is crucial for maintainability and efficiency. It largely depends on the specific language or set of languages used in the project. A well-structured repository should have a logical hierarchy, clear separation of concerns, and follow established conventions for the chosen technology stack.  Refer [Python Good Practices](./python_good_practices.md) for more details.
-- **Use Descriptive Names:** Choose repository names that clearly indicate the project's purpose or content. A good practices is to name the repo with following nomenclature `{team}.{projectname}.{service}`. As an example, if AI team is  developing Content Classifier and it will be exposed as APIs, then a suitable name would be `ai.contentclassifer.api`
+- **Repo Structure:** The organization of files and directories within a repository is crucial for maintainability and efficiency. It largely depends on the specific language or set of languages used in the project. A well-structured repository should have a logical hierarchy, clear separation of concerns, and follow established conventions for the chosen technology stack. Refer [Python Good Practices](./python_good_practices.md#project-structuring) for more details.
+- **Use Descriptive Names:** Choose repository names that clearly indicate the project's purpose or content. A good practices is to name the repo with following nomenclature `{team}.{projectname}.{service}`. As an example, if AI team is  developing a Content Classifier that will be exposed as APIs, then a suitable name would be `ai.contentclassifer.api`
 - **Include a README:** Always create a comprehensive README file that explains the project's purpose, setup instructions, and usage guidelines.
 
 ### Branches
@@ -28,10 +26,10 @@ Let's go through individual steps in the lifecycle of using Github to discuss go
   - **Release branch:** `release/v1.2.0`
   - **Individual branch**: `mohit/10-10-2024-updates`
 
-- **Keep Branches Up-to-Date:** Regularly merge or rebase your feature branches with the `dev` or `main` or `master` branch to avoid merge conflicts and ensure your code is always compatible with the latest changes.
+- **Keep Branches Up-to-Date:** Regularly merge or rebase your feature branches with the `dev` or `main` or `master` branch *(whichever branch you intend to merge to later)* to avoid merge conflicts and ensure your code is always compatible with the latest changes.
 
 !!! Warning
-    Do not push changes directly to main branches like `dev` branch. Make sure to create a feature branch, make changes, test them, and then raise a PR to merge the changes into the main branch. More on this below. 
+    Do not push changes directly to main branches. Make sure to create a feature branch, make changes there, test them, and then raise a PR to merge the changes into the main branch. More on this below. 
 
 ### Committing Changes
 
@@ -41,7 +39,7 @@ Let's go through individual steps in the lifecycle of using Github to discuss go
   - **Refer to issues or pull requests:** If your commit is related to a specific issue or pull request, include a reference to it in the commit message. Ex: `Fixed #OB-101`
   - **Keep it short:** Aim for a commit message that is no more than 50 characters long in general.
 
-## Pull Requests
+### Pull Requests
 
 - **Pre-PR:** Before even raising a PR, make sure you
   - **Thoroughly Test Changes:** Before creating a pull request, ensure your changes work as expected by running unit tests and/or manual testing. It is also important to perform a thorough test of other modules that might have been impacted due to the changes and perform a random check on other modules to make sure there is no sporadic impact on the overall project.
@@ -66,7 +64,7 @@ Let's go through individual steps in the lifecycle of using Github to discuss go
     ```
 
   - **Add reviewers:** When creating a pull request, assign appropriate team members to review your code. Choose reviewers who are familiar with the project and can provide valuable feedback.
-  
+
 - **Post-PR:**
   - **Review Code Carefully:** Reviewer should thoroughly go through the changelog in code and suggest improvements if any by adding comments. Do not approve the PR unless you are satisfied with the code’s quality, impact and implementation.
   - **Address Feedback Promptly:** Conversations to comments and suggestions from reviewers should be addressed in a timely manner.