Skip to content

Latest commit

 

History

History
149 lines (111 loc) · 6.59 KB

CONTRIBUTING.md

File metadata and controls

149 lines (111 loc) · 6.59 KB
Raw

Contributing to SystemLink Operations Handbook

Contributions to SystemLink Operations Handbook are welcome from all!

systemlink-operations-handbook is managed via git, with the canonical upstream repository hosted on GitHub.

systemlink-operations-handbook follows a pull-request model for development. If you wish to contribute, you will need to create a GitHub account, fork this project, push a branch with your changes to your project, and then submit a pull request.

See GitHub's official documentation for more details.

When to add content to the handbook

Add content to the SystemLink Operations Handbook in any of the following situations:

  • The primary audience for this content is IT professionals.
  • The content is primarily example code.
  • The content covers more advanced or corner-case scenarios than the ni.com help.
  • Customers need the content sooner than the current release timeline can deliver it.
  • The content covers a preview feature. If this is the case, remember to add a note saying so.

Otherwise, raise an issue in GitHub or leave feedback on ni.com to request help content.

Developer Setup

Hosting handbook locally

Before making changes to markdown files in the handbook, set up a Python virtual environment for using MkDocs:

  1. Download and install Python (NI recommends 3.8 or later)
  2. Download and install Microsoft Build Tools for C++
    • MSVC C++ Build Tools
    • Windows SDK
  3. (Optional) Create a virtual environment named .venv in the current directory by running python -m venv .venv. Each time you open a new command window, activate the environment before running mkdocs commands:
    • Windows users: run .venv\Scripts\activate
    • Linux or Mac users: run source .venv/bin/activate
  4. Upgrade pip by running python -m pip install --upgrade pip
  5. Install dependencies by running pip install -r requirements.txt

For more information and installation options, see MkDocs - Installation.

Linting Markdown Files

All markdown must pass linting rules before a PR may be merged. The markdownlint plugin for VSCode is recommended. The .markdownlint.yaml file contains overrides to linting rules for the handbook.

Previewing Changes to Markdown Files

Preview changes you make to handbook content before you submit them. In the MkDocs environment you set up, run the following command to start a local testing server:

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.58 seconds
[I 200731 15:48:28 server:334] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 200731 15:48:28 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 200731 15:48:28 handlers:64] Start detecting changes
INFO    -  Start detecting changes

To access the preview, open a browser and navigate to http://127.0.0.1:8000/. For more information and configuration options, see MkDocs - Getting Started.

Authoring Handbook Chapters

  • Review chapter-template.md and use as a starting point and reference to the structure and style of the handbook.
  • To add a chapter, update the arrange section in handbook/.pages in this repository to reference the new chapter directory.

Building a Local Copy of the Handbook

The handbook uses MkDocs to produce a static HTML website that any web server can host. Build your own local copy of this handbook to access it without internet connectivity. In the MkDocs environment you set up, run the following command to build a local copy:

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: site
INFO    -  Documentation built in 0.52 seconds

MkDocs builds the content into a site subdirectory, which you can copy into any web server. For more information about building, see MkDocs - Building the site.

Upgrading Python Dependencies

The included requirements.txt file lists specific versions of each dependency and transitive dependency needed to build the handbook. To install the latest versions, reference the requirements-latest.txt file instead, by running pip install -r requirements-latest.txt.

Upgrading versions may require changes to stylesheets or overrides files. Specifically, see the patches README for information about upgrading the mkdocs-material dependency.

After installing new versions, generate an updated requirements.txt file by running pip freeze > requirements.txt.

Developer Certificate of Origin (DCO)

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

(taken from developercertificate.org)

See LICENSE for details about how systemlink-operations-handbook is licensed.