|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Like the official [Carpentries][c-site] sites [Software Carpentry][swc-site], [Data Carpentry][dc-site], |
| 4 | +and [Library Carpentry][lc-site]; [HPC Carpentry][hpcc-site] is an open source project, |
| 5 | +and we welcome contributions of all kinds: |
| 6 | +blog posts, |
| 7 | +fixes to existing material, |
| 8 | +bug reports, |
| 9 | +and reviews of proposed changes are all welcome. |
| 10 | + |
| 11 | +## Contributor Agreement |
| 12 | + |
| 13 | +By contributing, |
| 14 | +you agree that we may redistribute your work under [our license](LICENSE.md). |
| 15 | +Everyone involved in i[HPC Carpentry][hpcc-site] |
| 16 | +agrees to abide by our [code of conduct][conduct]. |
| 17 | + |
| 18 | + |
| 19 | +## How to Contribute a Fix or Suggested Change |
| 20 | + |
| 21 | +The easiest way to get started is to file an issue |
| 22 | +to tell us about a spelling mistake, |
| 23 | +some awkward wording, |
| 24 | +or a factual error. |
| 25 | +This is a good way to introduce yourself |
| 26 | +and to meet some of our community members. |
| 27 | + |
| 28 | +1. If you do not have a [GitHub][github] account, |
| 29 | + you can [send us comments by email][contact]. |
| 30 | + However, |
| 31 | + we will be able to respond more quickly if you use one of the other methods described below. |
| 32 | + |
| 33 | +2. If you have a [GitHub][github] account, |
| 34 | + or are willing to [create one][github-join], |
| 35 | + but do not know how to use Git, |
| 36 | + you can report problems or suggest improvements by [creating an issue][issues]. |
| 37 | + This allows us to assign the item to someone |
| 38 | + and to respond to it in a threaded discussion. |
| 39 | + |
| 40 | +3. If you are comfortable with Git, |
| 41 | + and would like to add or change material, |
| 42 | + you can submit a pull request (PR). |
| 43 | + |
| 44 | +## Where to Contribute |
| 45 | + |
| 46 | +1. If you wish to change the website, |
| 47 | + please work in <https://github.com/hpc-carpentry/hpc-carpentry.github.io>, |
| 48 | + which can be viewed at <https://hpc-carpentry.org>. |
| 49 | + |
| 50 | +2. If you wish to change CSS style files, tools, |
| 51 | + or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`, |
| 52 | + please work in <https://github.com/carpentries/carpentries.org> (on which |
| 53 | + this website is based). |
| 54 | + |
| 55 | +## How to Contribute a Blog Post |
| 56 | + |
| 57 | +1. If you wish to contribute a blog post, |
| 58 | + please work in <https://github.com/hpc-carpentry/hpc-carpentry.github.io>, |
| 59 | + which can be viewed at <https://hpc-carpentry.org>. |
| 60 | + |
| 61 | +2. Posts go in the `_posts` folder, which is divided up first by year, |
| 62 | + e.g. `2018`, and then by month, e.g. `04`. Be sure to start creating your file in |
| 63 | + the correct folder. |
| 64 | + |
| 65 | +3. Posts need to be created in [Markdown](https://guides.github.com/features/mastering-markdown/) and named |
| 66 | + according to this convention (all-lower-case filenames are preferred): |
| 67 | + |
| 68 | + `YYYY-MM-DD-filename.md` |
| 69 | + |
| 70 | + e.g. |
| 71 | + |
| 72 | + `2017-07-10-assess_report.md` |
| 73 | + |
| 74 | +4. In order to render correctly, posts need to have a [header block, which should be created like this example](https://raw.githubusercontent.com/carpentries/carpentries.org/main/_posts/2018/04/2018-04-11-launch-handbook.md), e.g. |
| 75 | + |
| 76 | +``` |
| 77 | +--- |
| 78 | +layout: page |
| 79 | +authors: ["Tracy Teal", "Maneesha Sane", "Belinda Weaver"] |
| 80 | +title: "Launching our New Handbook" |
| 81 | +teaser: "Find new pathways to a range of Carpentries material" |
| 82 | +date: 2018-04-11 |
| 83 | +time: "9:00:00" |
| 84 | +tags: ["Communications"] |
| 85 | +--- |
| 86 | +``` |
| 87 | + |
| 88 | +Separate the header block from the post proper by a new line. |
| 89 | + |
| 90 | +5. `Time`, but the other fields should be filled in. If there is more than one author, |
| 91 | + separate the author names like this: `["Name 1", "Name 2"]`. Separate any tags the same way. |
| 92 | + |
| 93 | +6. Images should be uploaded to the appropriate year in the `files/<year>/<month>` folder. Images should be linked using |
| 94 | + Markdown, and paths to the image should be relative. |
| 95 | + Example: |
| 96 | + ``` |
| 97 | +  |
| 98 | + ``` |
| 99 | + A web link should be used for images hosted elsewhere. |
| 100 | + Example: |
| 101 | + ``` |
| 102 | +  |
| 103 | + ``` |
| 104 | + |
| 105 | + If you are not sure how to add images in Markdown format, look at an [existing Software Carpentry post with a locally hosted image](https://raw.githubusercontent.com/swcarpentry/website/main/_posts/2017/06/2017-06-19-mqu-ttt.md) or [one with a web link](https://raw.githubusercontent.com/swcarpentry/website/main/_posts/2017/07/2017-07-10-assess_report.md) and copy the formatting from there. |
| 106 | + |
| 107 | +7. Once you have previewed your file, commit the Markdown file to your fork and start a Pull Request. We automatically run tests using [GitHub Actions](https://github.com/features/actions) on your Pull Requests. Please review your pull request a few minutes after you've submitted it to make sure those tests have passed. These tests look for valid YAML headers and make sure that the post will build properly. |
| 108 | + |
| 109 | +## Other Resources |
| 110 | +
|
| 111 | +General discussion of [HPC Carpentry][hpcc-site] |
| 112 | +happens on the [discussion mailing list][discuss-list], |
| 113 | +which everyone is welcome to join. |
| 114 | +You can also [reach us by email][contact]. |
| 115 | +
|
| 116 | +[contact]: mailto:[email protected] |
| 117 | +[conduct]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html |
| 118 | +[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry |
| 119 | +[dc-lessons]: https://datacarpentry.org/lessons/ |
| 120 | +[dc-site]: https://datacarpentry.org/ |
| 121 | +[discuss-list]: https://carpentries.topicbox.com/groups/discuss-hpc |
| 122 | +[github]: http://github.com |
| 123 | +[github-flow]: https://guides.github.com/introduction/flow/ |
| 124 | +[github-join]: https://github.com/join |
| 125 | +[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github |
| 126 | +[issues]: https://github.com/hpc-carpentry/hpc-carpentry.github.io/issues/ |
| 127 | +[repo]: https://github.com/hpc-carpentry/hpc-carpentry.github.io |
| 128 | +[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry |
| 129 | +[swc-lessons]: http://software-carpentry.org/lessons/ |
| 130 | +[swc-site]: http://software-carpentry.org/ |
| 131 | +[lc-issues]: https://github.com/issues?q=user%3Adatacarpentry |
| 132 | +[lc-lessons]: https://librarycarpentry.org/lessons/ |
| 133 | +[lc-site]: https://librarycarpentry.org/ |
0 commit comments