Skip to content

Latest commit

 

History

History
221 lines (152 loc) · 8.75 KB

CONTRIBUTING.md

File metadata and controls

221 lines (152 loc) · 8.75 KB
Raw

Contributing

Code of conduct | Contact admins | Open an Issue

Thank you for wanting to contribute to the Sensu Community! Please read and follow our code of conduct. Contact sensu/sensu-docs administrators at docs@sensu.io if needed.

About the Sensu docs

Sensu documentation is written in Goldmark Markdown, built with Hugo, and maintained on GitHub in the sensu/sensu-docs repo.

Goldmark Markdown is largely GitHub-flavored Markdown. The Sensu docs project requires Hugo version 0.101.0 or later. You'll also need to install Git to contribute from your command line.

Contributing instructions

These instructions will help you fork this repository, create a branch, add your DCO sign-off, and submit a pull request (PR) either in your browser or from your command line.

After your PR is submitted, project maintainers will review it. If you'd like to mark your PR as work in progress, add [WIP] to the PR title.

If you have questions or want to ensure a PR is reviewed, please reach out in the Sensu Docs category of the Sensu Community Forum on Discourse or the #documentation channel of the Sensu Community Slack.

Browser workflow for PRs

  1. From any documentation page on docs.sensu.io, select Edit this page (look under the left-navigation menu or at the top-right corner on any page). The corresponding Markdown file for the page will open in GitHub, create a fork of the sensu/sensu-docsrepository, and create a new branch for your contribution.

  2. Make your changes to the Markdown content.

  3. Select "Propose changes" and follow the prompts to submit a pull request.

NOTE: Include a DCO Signed-off-by statement as the last line in your commit message.

If you have any questions, please open an issue.

Command line workflow for PRs

  1. From the main page of the sensu/sensu-docs repository, click the Fork button at the top-right of the page.

  2. From the directory where you want to save the sensu-docs code, clone this repository and set up the upstream remote:

git clone https://github.com/REPLACEME/sensu-docs/
# or: git clone git@github.com:REPLACEME/sensu-docs.git

cd sensu-docs

git remote add upstream https://github.com/sensu/sensu-docs.git
# or: git remote add upstream git@github.com:sensu/sensu-docs.git
  1. Update your local fork:
git fetch upstream
git checkout main
git rebase upstream/main
  1. Create a new branch with a descriptive name to contain your change:
git checkout -b fix-code-samples

  1. Build the Sensu docs site locally and test your changes.

    See the Sensu Docs style guide for formatting instructions and style conventions.

    To build the site, run yarn. This builds the search index and compiles the static content. You can then run yarn run server to view the docs site in real-time as you edit.

  2. Commit your changes with a descriptive commit message.

    NOTE: Include a DCO Signed-off-by statement (git commit --signoff) with your commit.

git commit -am "fix invalid JSON"
  1. Repeat the commit process as often as you need and edit/test/repeat. To add minor edits to your last commit:
git add -u
git commit --amend

This project uses commit hooks to test the build whenever making a commit.
  1. When you're ready to commit for review (or if you just want to establish an offsite backup or your work), push your branch to your fork on GitHub:
git push origin feature/myfeature

If you recently used `commit --amend`, you may need to force push:

git push -f origin feature/myfeature
  1. Create a pull request by visiting sensu/sensu-docs on GitHub and following the prompts. We'd appreciate it if you allow edits to your PR from Sensu docs maintainers.

Guidelines

Developer's Certificate of Origin (DCO)

To make a good-faith effort to ensure that contributions meet the criteria of the MIT License, Sensu follows the Developer's Certificate of Origin (DCO) process.

The DCO is an attestation attached to every contribution you make. In the commit message of your contribution, add a Signed-off-by statement and thereby agree to the DCO, which is listed below and at https://developercertificate.org/:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


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.

DCO sign-off

The DCO Signed-off-by statement attests that you agree to the DCO. DCO sign-off is required for every commit to the sensu/sensu-docs repo.

You can sign off in your commit messages in your browser or on the command line.

Browser workflow for DCO sign-off

If you are creating your PR directly in your browser, add your DCO Signed-off-by statement as the last line in your commit message.

Follow this example, but before you click Propose changes to create your PR, replace Miles Dyson and mdyson@cyberdyne.com with the first and last name and email address associated with your GitHub user account:

DCO sign-off in browser

GitHub will include your Signed-off-by statement in your commit, so your contributions will be DCO-compliant.

Command line workflow for DCO sign-off

You can configure your local git instance to add your DCO Signed-off-by statement to every commit. Before you run the following code, replace Miles Dyson and mdyson@cyberdyne.com with the first and last name and email address associated with your GitHub user account.

git config --global user.name "Miles Dyson" 
git config --global user.email mdyson@cyberdyne.com

Now, every time you commit new code in git, add the -s flag to your commit message to include your Signed-off-by statement:

git commit -s -m "Your commit message goes here"

Git will add your Signed-off-by statement along with your commit, so your contributions will be DCO-compliant.

Update multiple versions of the docs

Some contributions apply to multiple versions of Sensu, or other sections of the documentation. Please copy your edits to all applicable Sensu docs versions. 🙏

Contribute elsewhere

This repository is one of several that are community-supported around Sensu. See all the ways you can get involved by visiting the Community repository.

One of the most helpful ways you can benefit the Sensu community is by writing about how you use Sensu. Write up something on Medium, embed Gists for longer code samples, and let us know in Slack or on Discourse! We'll publish it to the blog at blog.sensu.io.

Thank you!

We ❤️ your participation and appreciate the unique perspective you bring to our community. Keep sharing the #monitoringlove.