Task: Remove Make Documentation from Magma Documentation Repository

[lucaaamaral]

Task: Remove Make Documentation from Magma Documentation Repository

Objective

Remove all Make-related documentation from the magma/magma-documentation repository, as part of the approved plan to finalize the deprecation and removal of Make from the Magma project’s build and installation processes (see Issue #15756). This task aligns with the Magma Technical Steering Committee (TSC) approval and the ongoing efforts to clean up Make-related code, as demonstrated in Pull Request #14857.

Background

The Magma TSC has approved the final deprecation and removal of Make from Magma’s build and installation processes, as Make has been fully replaced by Bazel for building and Ansible for installation. Make is already marked as deprecated, but its documentation remains in the magma/magma-documentation repository, causing potential confusion for users and contributors. Pull Request #14857 has initiated the cleanup of Make targets in the Access Gateway (AGW), and this task extends that effort by removing Make-related documentation to ensure consistency with the adoption of Bazel and Ansible, with Ansible deployment scripts in the deployment repository replacing Make-based scripts in lte/gateway/deploy, orc8r/cloud/docker, and the NMS Docker build.

Task Details

1. Identify Make-Related Documentation

   • Search the magma/magma-documentation repository for all files and sections referencing Make, including:
     • Build instructions using Makefiles.
     • Installation guides referencing Make-based scripts in lte/gateway/deploy (bash scripts), orc8r/cloud/docker (Python scripts), or the NMS Docker build.
     • Tutorials, examples, or FAQs mentioning Make or Make-based workflows.
   • Document the list of files/sections to be modified or deleted.

2. Remove Make Documentation

   • Delete or update identified files to remove all Make-related content, ensuring no references to Makefiles or Make-based deployment scripts remain.
   • Verify that removal does not disrupt references to Bazel for building or Ansible for installation, particularly the Ansible deployment scripts in the deployment repository.
   • Ensure that documentation for the three deployment contexts (lte/gateway/deploy, orc8r/cloud/docker, and NMS Docker build) is updated to reflect their replacement by Ansible scripts in the deployment repository.

3. Update Related Documentation

   • Add a note in the main documentation (e.g., README or build/installation overview) stating that Make has been deprecated and removed, directing users to Bazel for building and Ansible for installation, with specific references to the Ansible deployment scripts in the deployment repository.
   • Include a reference to the migration guide (to be created separately, as per Issue #15756) for users transitioning from Make to Bazel and Ansible.
   • Highlight that Make-based scripts in lte/gateway/deploy, orc8r/cloud/docker, and the NMS Docker build have been replaced by unified Ansible deployment scripts.

4. Testing and Validation

   • Validate that all Make-related content has been removed by searching the repository for keywords like "Make," "Makefile," or related terms.
   • Ensure that the remaining documentation is consistent, functional, and correctly references Bazel and Ansible workflows, including the Ansible deployment scripts in the deployment repository.
   • Test documentation links to confirm no broken references remain.

5. Pull Request and Review

   • Submit a pull request to the magma/magma-documentation repository with the changes.
   • Include a clear description in the PR, referencing Issue #15756 and Pull Request #14857, and noting TSC approval for Make’s removal.
   • Request review from the Magma documentation maintainers.

Timeline

• Start Date: Initiate immediately following TSC approval, aligning with the next release cycle for the final deprecation announcement.
• Completion Date: Complete removal of Make documentation, before the release designated for Make’s full removal (as per Issue #15756).
• Key Actions:
  • Identify and document Make-related content.
  • Remove/update documentation and validate changes.
  • Submit and address feedback on the pull request.

Notes

• Make has already been replaced by Bazel for building and Ansible for installation, and its deprecated status is well-documented. This task focuses on removing outdated documentation to prevent confusion.
• Coordinate with the team creating the migration guide to ensure users have clear instructions for transitioning to Bazel and Ansible, particularly for the deployment contexts previously handled by Make-based scripts.
• Engage with the Magma community (e.g., Slack or GitHub Discussions) to address any questions or concerns about the removal of Make documentation, emphasizing the stability of Ansible deployment scripts in the deployment repository.

Acceptance Criteria

• All Make-related documentation is removed from the magma/magma-documentation repository.
• A note about Make’s deprecation and removal is added to the main documentation, with pointers to Bazel for building and Ansible for installation, including specific references to the Ansible deployment scripts in the deployment repository.
• No broken links or references remain in the documentation.
• The pull request is approved and merged by the Magma documentation maintainers.

[lucaaamaral]

Assigned to @jorgevargasmor