-
Notifications
You must be signed in to change notification settings - Fork 593
Contributing Documentation
This page describes how to contribute changes to the Magma documentation including the Contributor Guide.
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.
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.
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;
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.
- Magma-specific
- 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
- Title:
- Deploy guide (install)
- Title:
Install Orchestrator
,Install Access Gateway
- ID:
deploy_install
- Filename:
lte/deploy_install.md
,orc8r/deploy_install.md
- Title:
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.
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.
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.
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.
-
Add/delete a doc: add/delete the doc to/from the appropriate path under
docs/readmes/
, then updatesidebars.json
to include/remove the doc. Afterwards, runcd ${MAGMA_ROOT}/docs && make dev
to have the changes to the file structure reflected in the generated filedocs/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.⚠️ 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 ofversioned_docs/version-X.X.1
. Instead, the X.X.1 documentation will use the version of the doc inversioned_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 fromversioned_docs/version.X.X.0
toversioned_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.
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
Generate and run a local server serving your changes
cd ${MAGMA_ROOT}/docs && make dev
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.
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)
.
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.
Magma Website • Docs • Code • Contributing • Wiki