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