fix(handbook): add links and improve syntax

Author: gsanchietti

handbook/commit_messages.md

@@ -6,7 +6,7 @@ nav_order: 6
 
 # Commit Messages Style Guide
 
-A commit message is a brief description of the changes made in a commit. It is a way to communicate the purpose of the change to other developers.
+A commit message is a brief description of the changes made in a [commit](https://git-scm.com/docs/git-commit). It is a way to communicate the purpose of the change to other developers.
 A good commit message helps to understand the changes made in the commit and why they were made.
 
 All Nethesis projects follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages.

handbook/index.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Development Handbook
+title: Development process
 nav_order: 1
 ---
 
@@ -41,7 +41,7 @@ There are two communities that contribute significantly:
 
 - [NethServer Community](https://community.nethserver.org/): This community consists of users and developers who volunteer their time. The forum is in English and open to everyone. It is the primary place for feature requests, support, and bug reports. Without this community, the project would not exist.
 
-- [Nethesis Partner Community](https://partner.nethesis.it/): This community includes partners and customers. The forum is in Italian and focuses on commercial support, feature requests, and support. They provide substantial contributions to the project roadmap as they financially support the project. Access is reserved for partners.
+- [Nethesis Partner Community](https://partner.nethesis.it/): This community includes partners and customers. The forum is in Italian and focuses on commercial support, feature requests and support. They provide substantial contributions to the project roadmap as they financially support the project. Access is reserved for partners.
 
 The main tool used is [GitHub](https://github.com), where the code is hosted, and the development process is managed. Repositories are organized into organizations. Nethesis has two organizations:
 
@@ -50,26 +50,25 @@ The main tool used is [GitHub](https://github.com), where the code is hosted, an
 
 ## General workflow
 
-The development workflow for Nethesis projects involves several steps to ensure quality and efficiency. Here is a detailed description of the process:
+The development process is heavily based on the use of GitHub and follows the GitHub flow methodology.
+GitHub Flow is a lightweight, branch-based workflow for managing work. It involves creating a branch for each 
+feature or bug fix, committing changes to that branch, opening a pull request to discuss and review the changes,
+and merging the branch into the main branch once approved. It emphasizes collaboration, continuous delivery,
+and integration. For more details, visit [GitHub Flow official documentation](https://docs.github.com/en/get-started/using-github/github-flow).
+
+The development workflow for NethServer projects involves several steps to ensure quality and efficiency. Here is a detailed description of the process:
 
-1. **Bug or Feature Collection**: Issues are collected from internal channels (private chats, helpdesk) or external channels such as community forums.
-2. **Issue Formalization**: The collected issues are formalized into GitHub issues. This task is usually delegated to a developer but can also be performed by other roles such as the project manager. The issue must be added to a project board and can be added to a milestone if it must be planned for a specific release.
-3. **Issue Assignment**: The issue is assigned to a developer who implements the solution in a separate branch and opens a pull request. If the issue requires changes to the user interface, the issue is assigned to a UI/UX designer before starting the development process.
+1. **Bug or Feature Collection**: Issues are collected from public channels such as community forums or internal channels (private chats, helpdesk).
+   The [Product Manager (PM)](management/#product-manager) is responsible for collecting and organizing the issues.
+2. **Issue Formalization**: The collected issues are formalized into GitHub [issues](issues). This task is usually delegated to the PM or to a [developer](management/#developer) but can also be performed by other roles such as a support team member. The issue must be added to a project board and can be added to a milestone if it must be planned for a specific release.
+3. **Issue Assignment**: The issue is assigned to a developer who implements the solution in a separate branch and opens a [Pull Request (PR)](pull_requests). If the issue requires changes to the user interface, the issue is assigned to a UI/UX designer before starting the development process.
 4. **Code Review**: The code is subjected to a code review by one or more developers to ensure quality and adherence to coding standards.
 5. **Pull Request Approval and Merge**: Once the pull request is approved, it is merged into the main branch.
 6. **Automated Build and Test Process**: The build and test processes are automatically executed to verify the changes.
-7. **Quality Assurance (QA)**: The output of the build process, whether a module or a package, is subjected to QA testing.
+7. **Quality Assurance (QA)**: The output of the build process, whether a module or a package, is subjected to [Quality Assurance (QA)](management/#qa-team-member-testing) testing.
 8. **Release or Rework**:
-  - If the QA process is successful, the module or package is released, and the issue is closed.
+  - If the QA process is successful, the [packager](management#packager) can release the module or package, and the issue is closed.
   - If the QA process fails, the issue is returned to the developer for correction, and the process restarts from step 3.
-  
-## Tools and methodologies
-
-The development process is heavily based on the use of Git and GitHub and follows the GitHub flow methodology.
-GitHub Flow is a lightweight, branch-based workflow for managing work on GitHub. It involves creating a branch for each 
-feature or bug fix, committing changes to that branch, opening a pull request to discuss and review the changes,
-and merging the branch into the main branch once approved. It emphasizes collaboration, continuous delivery,
-and integration. For more details, visit [GitHub Flow official documentation](https://docs.github.com/en/get-started/using-github/github-flow).
 
 ## Handbook structure
 

handbook/issues.md

@@ -30,7 +30,10 @@ There two main type of issues:
 
 Bug and feature issues will always produce some code changes inside one or more Git repositories.
 Usually this type of issue are the parent issue for one or more sub-issues.
-The QA should always test the parent issue, not the sub-issues.
+
+The QA of the code should always test the parent issue, not the sub-issues.
+Still, sub-issues of type **Design** can pass to the testing state when the mockup needs to be reviewed. When the mockup is approved, the sub-issue can be 
+moved to verified state or directly closed.
 
 Sub-issues are tasks that are part of the parent issue. They can be of different types:
 
@@ -49,6 +52,14 @@ Sub-issues are tasks that are part of the parent issue. They can be of different
 
 An issue can track a feature, a bug, or a task.
 
+Issues are not a to-do list. Issues track the status changes of a job, the
+output of the job will be a new container image, in case of NethServer, resolving the issue itself.
+If you are exploring some esoteric paths for new feature or hunting
+something like a [heisenbug](http://en.wikipedia.org/wiki/Heisenbug>),
+please open a discussion with your thoughts.
+Then create a new issue only when you’re ready to write a formal description
+and produce some output object.
+
 ### Feature
 
 A process for a new feature should be something like this:
@@ -58,7 +69,7 @@ A process for a new feature should be something like this:
 - if a feature is planned for the future it is also recorded in a [project
   draft card](https://github.com/orgs/NethServer/projects/8)
 
-- ongoing development can be tracked inside a [draft pull request](#draft-pull-requests)
+- ongoing development can be tracked inside a [draft pull request](/pull_requests/#draft-pull-requests)
 
 - once the work on the feature starts, open the issue on GitHub:
   - for [NethServer or NethVoice](https://github.com/NethServer/dev/issues/new)
@@ -83,19 +94,10 @@ By the way, it’s perfectly reasonable not to fill issues for
 occasional small fixes, like typos in translations.
 
 When implementing small fixes, always avoid commits to the main branch.
-Open a [pull request](#pull-requests) and carefully describe the problem.
+Open a [pull request](/pull_requests) and carefully describe the problem.
 Creation of issues can be avoided only for trivial fixes which require
 no QA effort.
 
-Issues are not a to-do list. Issues track the status changes of a job, the
-output of the job will be a new container image, in case of NethServer, resolving the issue itself.
-If you are exploring some esoteric paths for new feature or hunting
-something like a [heisenbug](http://en.wikipedia.org/wiki/Heisenbug>),
-please open a discussion with your thoughts.
-Then create a new issue only when you’re ready to write a formal description
-and produce some output object.
-
-
 ## Writing issues
 
 How to write a bug report:
@@ -162,79 +164,53 @@ The process of handling an issue is described in the following sections.
 ### Developer
 
 The *Developer*.
-
 - Sets *Assignee* to himself.
-
-- Sets the *Project* to `NethServer 8`, `NethVoice 8`, or `NethSecurity`.
-
-- Bundle his commits as one or more GitHub [pull requests](#pull-request)
-
+- Sets the *Project* to `NethServer`, `NethVoice`, or `NethSecurity`.
+- Bundle his commits as one or more GitHub [pull requests](/pull_request). 
 - For *features** *enhancements*, writes the test case (for *bugs* the procedure to
   reproduce the problem should be already set).
-
-- After the pull request is merged, the developer should:
-
+- After the pull request has been approved and merged, the developer should:
   - remove all assignee from the issue
   - set the **testing** label
-
   It's the developer's responsibility to ensure that someone from the QA team will test the package.
-
-- Writes and updates the [documentation](#documentation) associated with the code:
-
+- Writes and updates the documentation associated with the code:
   - README.md inside the repository
   - Administrator Manual
   - Developer Manual, if needed
+  - User Manual, if needed
 
 If the issue is not valid, it must be closed using ``Closed as not planned``.
 A comment must convey the reason why it is invalid, like *"duplicate of (URL of issue), wontfix because ..."*.
 
 ### QA team member (testing)
 
 The *QA team member*.
-
 * Takes an issue with label **testing** and adds themselves to the *Assignee*
   field
-
 * Tests the package, following the test case documentation written by the
   *Developer*.
-
 * Tests the documentation changes, if present
-
 * When test finishes they remove the **testing** label.  If the test is
   *successful*, they set the **verified** label, otherwise they alert the
   *Developer* and the *Packager* to plan a new process iteration.
 
 ### Packager
 
-The *Packager* coordinates the *Developer* and *QA member* work.  After the
-*Developer* opens one or more pull requests:
-
-* Selects issues with open pull requests
-
-* Reviews the pull request code and merges it
-  The CI will build and upload a new container image
-
+The *Packager* coordinates the *Developer* and *QA member* work.  
 After the *QA member* has completed the testing phase:
-
 * Takes an issue with label **verified**
-
 * Commits a *release tag* (see [version numbering rules](../version_numbering)).
-
 * Pushes the *release tag* and commits to GitHub
-
 * Merges the documentation changes in the documentation repo. Also
   publishes the documentation by pushing the `latest` branch, if needed.
   Documentation repositories:
-
   - [NethServer and NethVoice](https://github.com/NethServer/ns8-docs/)
   - [NethSecurity](https://github.com/NethServer/nethsecurity-docs/)
-
   An application should not be released as "stable" until all documentation
 (developer, admin, user) is complete.
-
 * Closes the issue, specifying the list of released modules
 
-When the package is CLOSED, all related [documentation](#documentation) must be in place.
+When the package is CLOSED, all related documentation must be in place.
 
 At any time of the issue life-cycle they ensure that there are no release
 conflict with other issues.

handbook/management.md

@@ -15,6 +15,7 @@ nav_order: 2
 ### Product Manager
 
 The Product Manager oversees the overall development process, ensuring that the product meets the needs of users and stakeholders. They prioritize features and bug fixes, coordinate between different teams, and ensure that the project stays on track and aligns with the strategic goals.
+They are responsible for defining the product vision, creating the roadmap, and communicating with the community.
 
 ### User
 
@@ -37,6 +38,7 @@ Anyone can be a QA Team Member, but usually is one of the following:
 ### Packager
 
 The Packager is a developer that coordinates the work between developers and QA Team Members. They review and merge code changes, manage release tags, and ensure that documentation is updated and published. They also handle the final steps of closing issues and releasing modules.
+Usually the packager is the same person as the developer, but in some cases, it can be a different person.
 
 ## Meetings
 
@@ -61,11 +63,11 @@ Project boards are used to track the progress of issues and requests. They are d
 
 All projects have some common views:
 
-- **Current**: it shows the current status of the project, it contains all the issues inside the ongoing milestone; this view uses a kanban board
+- **Current**: it shows the current status of the project, it contains all the issues inside the ongoing [milestone](/milestones); this view uses a kanban board
 
-- **Backlog**: it contains all the issues that are not assigned to a milestone yet, or that are not ready to be worked on; this view uses a list of issues
+- **Backlog**: it contains all the issues that are not assigned to a [milestone](/milestones) yet, or that are not ready to be worked on; this view uses a list of [issues](/issues)
 
-The team working on a project can decide to add more views if needed, for example, a view for the next milestone, or a view for the next release.
+The team working on a project can decide to add more views if needed, for example, a view for the next milestone, or a view to measure the team load.
 
 Each column contains a set of cards, each card represents an issue or a feature request.
 
@@ -79,9 +81,9 @@ The project is divided into columns that represent the status of the card.
 A card can be an issue, a feature request, a bug report, or a task.
 The columns are:
 
-- **ToDo**: new issues are placed here, the team will evaluate them and assign the right labels and milestone.
-- **In Progress**: issues that are being worked on, they are assigned to a developer or a designer. I
-- **Testing**: issues that are ready for testing. The QA Team Member will verify that the code works as expected and meets the required standards.
+- **ToDo**: new issues are placed here, the team will evaluate them and assign the right [labels](/issues/#issue-labels) and [milestone](/milestones).
+- **In Progress**: issues that are being worked on, they are assigned to a developer or a designer.
+- **Testing**: issues that are ready for testing. The QA Team will verify that the code works as expected and meets the required standards.
 - **Verified**: issues that have passed testing and are verified to be working correctly, this issues are ready to be released by the packager.
 - **Done**: issues that have been completed and closed.
 

handbook/milestones.md

@@ -6,11 +6,11 @@ nav_order: 2
 
 # Milestones
 
-GitHub milestones are a way to track progress on groups of issues or pull requests in a repository. They help in planning and managing project timelines by setting due dates and associating related tasks.
+[GitHub milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) are a way to track progress on groups of issues or pull requests in a repository. They help in planning and managing project timelines by setting due dates and associating related tasks.
 
-All Nethesis projects use rolling releases, so milestones are used to organize the project and highlight significant goals achieved and upcoming priorities.
+All NethServer projects use rolling releases, so milestones are used to organize the project and highlight significant goals achieved and upcoming priorities.
 A milestone can be closed when all associated issues have been completed.
-Issues can be added while the milestone is in progress, and milestones must contain both bugs and features.
+[Issues](/issues) can be added while the milestone is in progress, and milestones must contain both bugs and features.
 Completed issues are released as they are finished, so updates are rolling; there is no need to wait for the milestone to be completed to release updates.
 
 A milestone indicates a general objective and is useful because it concludes with an announcement to the community, informing everyone about what has been accomplished.
@@ -22,7 +22,7 @@ Each open milestone should have:
 - an end date that is the release date, this is usually an estimate and can be changed as needed
 
 Please note that only issues can be assigned to a milestone, not pull requests or draft card.
-To overcome this limitation, an issue with type "Draft" can be created to be associated with a milestone.
+To overcome this limitation, an issue with [type "Draft"](/issues/#issue-types) can be created to be associated with a milestone.
 Product managers typically use draft issues to plan work for upcoming milestones.
 A draft issue contains a brief description of the feature, it could not contain a detailed description or acceptance criteria.
 The issue type will be changed once the analysis is complete, and it may also be split into multiple sub-issues if the work requires task separation.