Contributing Documentation - magma/magma GitHub Wiki

This page describes how to contribute changes to the Magma documentation including the Contributor Guide.

Overview of Documentation Structure and Sources

The Magma documentation website is generated through the Docusaurus tool and is hosted under the Linux Foundation's Magma page. Changes to the documentation made within the Magma GitHub repository will be reflected on within the Magma documentation website.

Magma's documentation is versioned based on releases which results in a new version of the documentation for every major or minor release. The group that is responsible for leading the release process will also be responsible to ensure that all relevant documentation is added to master prior to the release being cut.

Documentation Structure

In order to modify or add new documentation, users will need to navigate to the proper location within the docs GitHub repo. For edits to any versioned documents, users should navigate to the magma/docs/docusaurus/versioned_docs/ parent directory and select the appropriate subfolder or file. For edits to master, users should navigate to the magma/docs/readmes/ directory.

Finally, for any general changes such as updates to the sidebars, packages, or Docker components, users should utilize the magma/docs/docusaurus/ folder. The sidebars.json and siteConfig.js are the main entry points for updating the look and feel of the documentation site. The former determines which README docs are displayed, and the latter sets site-wide config values.

Diagrams within the documentation

GitHub as well as Docusaurus support Mermaid diagrams. Whenever possible use Mermaid diagrams instead of pictures to include a diagram in the documentation. You can find help regarding the Mermaid syntax in the respective documentation and some examples for GitHub and Docusaurus.

This shows an example mermaid created diagram:

graph LR;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Styling and Writing Conventions

The end-goal is uniform, approachable documentation, especially in the Docusaurus.

  • Write in plain English
    • Short sentences
    • Active verbs
    • Use "you" and "we"
    • Avoid nominalisations
    • Use lists
  • Use descriptive hyperlink text
    • Don't use "here" as the text for a hyperlink
  • Consistent capitalization and spelling
    • Magma-specific
      • Orc8r, Orchestrator
      • NMS
      • Magma
      • Mconfig
    • Magma-adjacent
      • K8s, Kubernetes
      • Helm
      • gRPC
      • eNodeB
    • Everyday words
      • metadata
      • use-case
    • Magma service names
      • state, subscriberdb, lte, etc.
  • Use long form of CLI flags
    • --deployment rather than -d.

Follow the existing conventions when naming and placing new READMEs. Notably,

  • Use short, concise verbs as section and document titles (e.g. "Upgrade", "Deploy", "Debug")
  • Guide names and format should match across Magma components (i.e. Orc8r's "Upgrade to v1.4" and AGW's "Upgrade to v1.4" should flow together logically)
  • A document's ID should match its filename

Some examples of proper naming

  • Upgrade guide (upgrade to v1.4)
    • Title: Upgrade to v1.4
    • ID: upgrade_1_4
    • Filename: lte/upgrade_1_4.md, orc8r/upgrade_1_4.md
  • Deploy guide (install)
    • Title: Install Orchestrator, Install Access Gateway
    • ID: deploy_install
    • Filename: lte/deploy_install.md, orc8r/deploy_install.md

Versioning Documentation

All versioned documentation is located under the magma/docs/docusaurus/versioned_docs/ folder. Prior to creating or editing documentation, ensure that the changes you are making are applied to the right versioned docs. If they are for an upcoming release, they can be placed within the master magma/docs/readmes/ directory.

Versioning Conventions

Each major release (Ex. 1.1.0, 1.2.0, 1.3.0, etc.) has its own corresponding documentation as part of the release. If any changes are made to a release update (Ex. 1.2.1, 1.2.2) then those changes will be updates to the initial X.X.0 release rather than creating a new documentation version.

Versioning Scheme

Major releases will all follow the X.X.0 convention while minor releases and updates will follow X.X.1, X.X.2, X.X.3 convention. Any release whether major or minor will be accompanied by corresponding release notes which will detail the latest changes to the Magma codebase.

Versioning Process

If you want to cut a new versioned documentation release, bring up the Docusaurus container

cd ${MAGMA_ROOT}/docs/docusaurus
docker-compose down
docker build --tag magma_docusaurus .
docker-compose -f docker-compose.yml -f docker-compose.publish.yml up --detach
docker-compose exec docusaurus bash`

From inside the container, build the site

yarn install
yarn build

Now you can create a new versioned release

yarn run version X.Y.0  # e.g. version 1.5.0

Commit all the new generated files and tweak the sidebars if you need to. Run make dev to preview your changes.

Modifying the Documentation

Making changes

  • Add/delete a doc: add/delete the doc to/from the appropriate path under docs/readmes/, then update sidebars.json to include/remove the doc. Afterwards, run cd ${MAGMA_ROOT}/docs && make dev to have the changes to the file structure reflected in the generated file docs/docusaurus/i18n/en.json.

  • Update a current doc: edit the relevant doc under docs/readmes/

  • Update a versioned doc: if appropriate, first update the corresponding current doc, then edit the relevant doc under docs/docusaurus/versioned_docs. Note that the documentation for the docusaurus is never backported to release branches, because the docusaurus for past versions is deployed from the versioned docs on the master branch. This does not apply to documentation in README files that are not part of the docusaurus.

    :warning: Note that due to the versioning system used by Docusaurus, if a doc has not been updated between versions, say between version X.X.0 and X.X.1, then this doc will not appear in the tree of versioned_docs/version-X.X.1. Instead, the X.X.1 documentation will use the version of the doc in versioned_docs/version-X.X.0. Therefore, if you want to make changes to such a doc in version X.X.1 but not in X.X.0, you need to copy the file from versioned_docs/version.X.X.0 to versioned_docs/version.X.X.1 before making your changes. An example of this can be seen in this pull request. This feature means that extreme care should be taken if deleting a doc from a previous version, as this may have unintended consequences for other versions.

Checking changes

Before pushing, verify your Markdown passes the linter. This is enforced by the markdown-lint CI check. See Markdownlint rules and Magma's Markdownlint config for more info

# Check if changes pass Markdown lints
cd ${MAGMA_ROOT}/docs && make precommit
# Automatically fix some of the lints
cd ${MAGMA_ROOT}/docs && make precommit_fix

Viewing changes locally

Generate and run a local server serving your changes

cd ${MAGMA_ROOT}/docs && make dev

Editing the Magma GitHub Wiki

In order to edit this document or other documents within in the Magma Contributor Guide Wiki you must first ensure your account is established as part of the Magma organization. Once you are a member of the organization you will see an "Edit" button located in the top right hand portion of each wiki page. Selecting this button will enable you to make edits to any page within the Magma Wiki.

Adding images to the Magma GitHub Wiki

To add images to the Wiki, you will need to clone the Wiki repository and commit them using git. Place you images in a subfolder with the same name as the page you are editing within the assets folder. You can link the images by using the full path to the repository root, e.g. ![your_image_alternative_text](assets/page-you-are-adding-the-image-to/image-name.png).

Contributing a blog post to the Magma website

The community welcomes blog posts to contribute your Magma story and share them on the magmacore.org website! Some ideas of topics to consider include:

  • Case study about your trial or production deployment of the project
  • An applicable use case and how the project fits into it as a solution
  • Features in the platform to highlight
  • Drawing attention to a Magma demo through a blog post

The project website is hosted on WordPress. In order to submit a blog post and get it published you need to send the text and relevant files to Kendall Waters Perez and Jill Lovato. Kendall and Jill will assist you with next steps and work with you on the publication timeline as well.