Skip to content

Commit 8708f82

Browse files
author
Trevor Keller
committed
Fix broken links, create refs for long URLs
1 parent cc7ebd6 commit 8708f82

File tree

1 file changed

+128
-110
lines changed

1 file changed

+128
-110
lines changed

‎CONTRIBUTING.md‎

Lines changed: 128 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,151 @@
11
# Contributing
22

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.
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.
109

1110
## Contributor Agreement
1211

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-
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].
1816

1917
## How to Contribute a Fix or Suggested Change
2018

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 comments to the [community email list][discuss-list].
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).
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).
4338

4439
## Where to Contribute
4540

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>.
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>.
4944

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).
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).
5449

5550
## How to Contribute a Blog Post
5651

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-
![Image Description]({{ site.filesurl }}/2017/07/myimage.jpg)
98-
```
99-
A web link should be used for images hosted elsewhere.
100-
Example:
101-
```
102-
![Image Description](https://web_address/pathway_to_full_image_filename)
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.
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+
e.g.
73+
74+
```yaml
75+
---
76+
layout: page
77+
authors: ["Tracy Teal", "Maneesha Sane", "Belinda Weaver"]
78+
title: "Launching our New Handbook"
79+
teaser: "Find new pathways to a range of Carpentries material"
80+
date: 2018-04-11
81+
time: "9:00:00"
82+
tags: ["Communications"]
83+
---
84+
```
85+
86+
Separate the header block from the post proper by a new line.
87+
88+
5. `Time`, but the other fields should be filled in. If there is more
89+
than one author, separate the author names like this:
90+
91+
```yaml
92+
["Name 1", "Name 2"]
93+
```
94+
95+
Separate any tags the same way.
96+
97+
6. Images should be uploaded to the appropriate year in the
98+
`files/<year>/<month>` folder. Images should be linked using
99+
Markdown, and paths to the image should be relative. Example:
100+
101+
```markdown
102+
![Image Description]({{ site.filesurl }}/2017/07/myimage.jpg "alt text")
103+
```
104+
105+
A web link should be used for images hosted elsewhere.
106+
Example:
107+
108+
```markdown
109+
![Image Description](https://web_address/pathway_to_full_image_filename)
110+
```
111+
112+
If you are not sure how to add images in Markdown format,
113+
look at an existing Carpentries post with a
114+
[locally hosted image][md-img-local] or
115+
[one with a web link][md-img-remote] and copy the formatting
116+
from there.
117+
118+
7. Once you have previewed your file, commit the Markdown file to
119+
your fork and start a Pull Request. We automatically run tests
120+
using [GitHub Actions][actions] on your Pull Requests. Please
121+
review your pull request a few minutes after you've submitted it
122+
to make sure those tests have passed. These tests look for valid
123+
YAML headers and make sure that the post will build properly.
108124

109125
## Other Resources
110126

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 the maintainers by email][contact].
127+
General discussion of [HPC Carpentry][hpcc-site] happens on the
128+
[discussion mailing list][discuss-list], which everyone is welcome
129+
to join. You can also [reach the maintainers by email][contact].
115130

116-
[contact]: mailto:[email protected]
131+
<!-- HPCC links -->
132+
133+
[actions]: https://github.com/hpc-carpentry/hpc-carpentry.github.io/actions
117134
[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/
135+
[contact]: mailto:[email protected]
121136
[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
126137
[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/
138+
[hpcc-site]: https://www.hpc-carpentry.org
139+
140+
<!-- Outside links -->
141+
142+
[c-site]: https://carpentries.org
143+
[dc-site]: https://datacarpentry.org/
144+
[github-join]: https://github.com/join
145+
[github]: http://github.com
146+
[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
133147
[lc-site]: https://librarycarpentry.org/
148+
[md-guide]: https://guides.github.com/features/mastering-markdown/
149+
[md-img-local]: https://github.com/carpentries/carpentries.org/blob/5524366743246303aa1dd80343dd4759685b44e9/_posts/2017/06/2017-06-19-mqu-ttt.md?plain=1#L29
150+
[md-img-remote]: https://github.com/carpentries/carpentries.org/blob/5524366743246303aa1dd80343dd4759685b44e9/_posts/2017/07/2017-07-10-assess_report.md?plain=1#L24
151+
[swc-site]: http://software-carpentry.org/

0 commit comments

Comments
 (0)