Merge pull request #364 from chipzoller/contributor-docs

Create contribution-related docs

3 files changed, 210 insertions, 5 deletions

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..99e53c7
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,78 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting project lead Chip Zoller via 
+[GitHub](https://github.com/chipzoller), 
+[Twitter](https://twitter.com/chipzoller) or
+[LinkedIn](https://www.linkedin.com/in/chipzoller). All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the 
+[Contributor Covenant][https://www.contributor-covenant.org/], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a98f0f2
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,109 @@
+# Contributing to Hugo Clarity
+
+Thank you for taking the time to contribute!
+
+Hugo Clarity is 
+[open-source](https://github.com/chipzoller/hugo-clarity/blob/master/LICENSE.md),
+and contributions are what make the open-source community such an amazing place
+to learn, inspire, and create. Any contributions you make will benefit others,
+and are **greatly appreciated**!
+
+When contributing, especially for the first time, consider starting by
+[creating an issue](https://github.com/chipzoller/hugo-clarity/issues/new) so
+you can get feedback from the maintainers and avoid unncessary work.
+
+**Note:** Hugo Clarity has a [code of conduct](CODE_OF_CONDUCT.md).
+Please follow it in all your interactions with the project.
+
+## Getting support and asking questions
+
+If you have questions about the project, are encountering something and aren't
+sure if it's a bug, or if you'd like to discuss an idea before filing a feature
+request, please use 
+[GitHub Discussions](https://github.com/chipzoller/hugo-clarity/discussions)
+rather than posting an issue.
+
+## Filing issues and requesting features
+
+You've found a bug in the source code, a mistake in the documentation or maybe
+you'd like a new feature? You can help us by
+[submitting an issue](https://github.com/chipzoller/hugo-clarity/issues).
+Before you create an issue, make sure to search the issue archive -- your issue
+may have already been addressed!
+
+Once a bug has been confirmed or a feature has been approved, you are welcome
+to [submit a Pull Request](#submit-a-pull-request) -- if you have the solution,
+please do tell us about it!
+
+### Helping us fix bugs
+
+We want to help you solve any problems you might be facing with the theme! In
+order to help us help you, create bug reports that are:
+
+- _Reproducible._ Include steps to reproduce the problem.
+- _Specific._ Include as much detail as possible: which version, what
+  environment, etc.
+- _Unique._ If other bug reports already exist about the same issue, add to
+  them rather than creating a new one.
+- _Scoped to a single bug._ One bug per report. We know this might be a little
+  tedious, but it makes it *much* easier to keep track of which bugs are fixed
+  and which still need work to be done.
+
+## How to submit a Pull Request
+
+1. Search our repository for open or closed
+   [Pull Requests](https://github.com/chipzoller/hugo-clarity/pulls) that
+   relate to your issue. You don't want to duplicate effort, and if one already
+   exists you can collaborate on that.
+
+2. Ensure that you plan to work consistent with the
+   [Developer Certificate of Origin](https://developercertificate.org/). This
+   confirms to us that you have the right to submit your contribution to an
+   open-source project (i.e. it is not proprietary or trade-secret code) and
+   that the record of your contribution will be recorded. **This is required
+   in order to contribute to Hugo Clarity**, and you'll need to confirm your
+   consent when committing, as shown below.
+
+3. Clone the project using [Gitpod](https://github.com/chipzoller/hugo-clarity#option-1a-development-in-the-browser)
+   or [locally on your machine](https://github.com/chipzoller/hugo-clarity#option-1b-development-on-your-machine)
+
+4. Create a new branch:
+
+   ```sh
+   git checkout -b amazing_feature
+   ```
+
+5. Do your work.
+
+6. Commit your changes:
+
+   ```sh
+   git commit -s -m 'Adding an amazing new feature'
+   ```
+
+  The `-s` flag is the short form of `--signoff` and signals to us that you are
+  abiding by the [Developer Certificate of Origin](https://developercertificate.org/) (see step 2, above).
+
+  If you are in an environment in which you cannot provide this cryptographic
+  signoff (for instance, Gitpod) you will need to leave a comment on the PR you
+  submit confirming that you certify compliance with the DCO.
+
+7. Repeat steps 5-6 as necessary.
+
+8. Unless your PR is documentation-only, **test your work 
+   [using Hugo extended](https://github.com/chipzoller/hugo-clarity#prerequisites)
+   to build a site.** When you submit your PR we'll run test-builds of a Hugo
+   site with your PR applied, so you'll save time if you fix any build issues
+   before submitting.
+
+9. Push the branch:
+
+   ```sh
+   git push origin amazing_feature
+   ```
+
+10. [Open a Pull Request](https://github.com/chipzoller/hugo-clarity/compare?expand=1)
+   and wait for feedback. Filling out the PR as requested will ensure your work
+   gets reviewed by maintainers promptly.
+
+## 🎉 **Thank you for your contribution!**
diff --git a/README.md b/README.md
index d5f2db0..f0619fc 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ A technology-minded theme for Hugo based on VMware's open-source [Clarity Design
     * [Logo alignment](#logo-alignment)
   * [Code](#code)
   * [Table of contents](#table-of-contents-1)
+  * [Pinning featured posts](#pinning-featured-posts)
   * [Notices](#notices)
   * [Custom CSS and JS](#custom-css-and-js)
   * [Custom Site Disclaimer](#site-disclaimer)
@@ -56,6 +57,9 @@ A technology-minded theme for Hugo based on VMware's open-source [Clarity Design
   * [Math notation](#math-notation)
   * [Open Street Map](#map)
   * [Search](#search)
+* [Contributing](#contributing)
+* [Code of conduct](#code-of-conduct)
+* [License](#license)
 
 ## Features
 
@@ -119,7 +123,7 @@ There are several ways to use this theme:
 
 For trying out the theme, quick experimentation, and to contribute Pull Requests, Gitpod is the easiest option. Use the button above and it will spin up a prebuilt environment with a site ready to go.
 
-If you want to contribute a PR, [this is a good overview of that process](https://jldec.me/using-gitpod-to-create-a-pr), and there's also an [optional browser extension](https://www.gitpod.io/docs/browser-extension).
+If you want to contribute a PR, [this is a good overview of that process](https://jldec.me/using-gitpod-to-create-a-pr), and there's also an [optional browser extension](https://www.gitpod.io/docs/browser-extension). [Read more about contributing to Hugo Clarity](CONTRIBUTING.md)
 
 ### Option 1b: Development on your machine
 
@@ -133,6 +137,8 @@ hugo server --themesDir ../..
 
 > Note that while this is a good way to work on Hugo Clarity, isn't a good way to work on your own site, since it uses the content from `exampleSite`, and wouldn't be aware of any overrides your site might apply to the theme.
 
+[Read more about contributing to Hugo Clarity](CONTRIBUTING.md)
+
 ### Option 2: Hugo modules
 
 This option arguably requires the least effort to run and maintain your website with the Hugo Clarity theme.
@@ -642,6 +648,12 @@ Each article can optionally have a table of contents (TOC) generated for it base
 
 ![Article table of contents](https://github.com/chipzoller/hugo-clarity/blob/master/images/article-toc.png)
 
+### Pinning featured posts
+
+This allows you to show the featured posts at the top of the post list.
+
+Use the [site configuration option](#global-parameters) `pinFeatured` to enable/disable it, and the option `numberOfPinnedPosts` to control how many posts to be pinned.
+
 ### Custom CSS and JS
 
 To minimize HTTP requests per page, we would recommend loading CSS styles and JavaScript helpers in single bundles. That is to say, one CSS file and one JavaScript file. Using Hugo minify functions, these files will be minified to optimize the size.
@@ -858,7 +870,7 @@ The site configuration option `showRelatedInArticle` controls if this option is
 
 Likewise, the site configuration option `showRelatedInSidebar` controls if related content is shown on the sidebar. There is no corresponding option within a post to disable this.
 
-### Map
+### Maps
 
 #### Creating and including a map
 
@@ -927,8 +939,14 @@ __Search Scope__
 
      For example, with the above setup, searching from the homepage will produce results from the entire site.
 
-### Pinning Featured Posts
+## Contributing
 
-This allows you to show the featured posts at the top of the post list.
+Please read our [contribution guidelines](CONTRIBUTING.md), and thank you for being involved!
+
+## Code of conduct
+
+Hugo Clarity has a [code of conduct](CODE_OF_CONDUCT.md). Please follow it in all your interactions with the project.
+
+## License
 
-Using the site configuration option `pinFeatured` to enable/disable it, and the option `numberOfPinnedPosts` to control how many posts to be pinned.
\ No newline at end of file
+Hugo Clarity is open-sourced under the [MIT license](https://github.com/chipzoller/hugo-clarity/blob/master/LICENSE.md).
\ No newline at end of file