/
CONTRIBUTING.html
145 lines (143 loc) · 4.77 KB
/
CONTRIBUTING.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
<!DOCTYPE html>
<html>
<head>
<title>Author Carpentry</title>
<link rel="stylesheet" href="css/site.css">
</head>
<body>
<header>
<a href="http://authorcarpentry.github.io"><img src="img/AClogo.jpg" alt="Author Carpentry logo"></a>
</header>
<nav>
<ul>
<li>
<a href=".">Lesson</a>
</li>
<li>
<a href="00-getting-started.html">Getting Started</a>
</li>
<li>
<a href="01-markdown.html">Intro to Markdown</a>
</li>
<li>
<a href="02-modifying-appearance.html">Document Appearance</a>
</li>
<li>
<a href="03-dynamic.html">Dynamic Documents</a>
</li>
<li>
<a href="04-publishing.html">Publishing</a>
</li>
<li>
<a href="mailto:authorcarpentry@library.caltech.edu">Contact Us</a>
</li>
</ul>
</nav>
<section>
<h1 id="contributing">
Contributing
</h1>
<p>
<a href="http://authorcarpentry.github.io">AuthorCarpentry</a> is an open source project, and we welcome contributions of all kinds: new lessons, fixes to existing material, bug reports, and reviews of proposed changes are all welcome.
</p>
<h2 id="contributor-agreement">
Contributor Agreement
</h2>
<p>
By contributing, you agree that we may redistribute your work under <a href="LICENSE.md">our license</a>. In exchange, we will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community. Everyone involved in <a href="http://authorcarpentry.github.io">Author Carpentry</a> agrees to abide by our <a href="CONDUCT.md">code of conduct</a>.
</p>
<h2 id="editing-lesson-content">
Editing Lesson Content
</h2>
<p>
All lesson content is written in markdown (.md) files. We use <a href="https://github.com/caltechlibrary/mkpage">mkpage</a> version 1.0+ to render lesson content into .html pages. Install mkpage from the Caltech Library repository at https://github.com/caltechlibrary/mkpage. There is a different mkpage available via rpm that won’t work for our application. While GitHub can render content, we use mkpage so lesson content can be viewed independent from a web connection.
</p>
<h2 id="working-with-github">
Working With GitHub
</h2>
<ol type="1">
<li>
<p>
Fork the <code>authorcarpentry/lesson-name</code> repository on GitHub.
</p>
</li>
<li>
<p>
Clone the repository to your local computer by using the “Clone” link at the top left corner of the repository page. In a local terminal window type ‘git clone <em>link</em>’
</p>
</li>
<li>
<p>
Make your changes to the .md files using your favorite text editor.
</p>
</li>
<li>
<p>
Render your content by typing ./mk-website.bash
</p>
</li>
<li>
<p>
(Optional) View your changes locally by typing ‘ws’ and pointing your web browser to http://localhost:8000
</p>
</li>
<li>
<p>
Upload your changes to your GitHub account by typing ./publish.bash (Does a git commit and push)
</p>
</li>
<li>
<p>
On the your GitHub repository site ‘https://github.com/username/lesson-name’ add a new branch by using the branch dropdown. Choose something that describes the changes you’ve made like <code>fixing-typos-in-shell-lesson</code> or <code>adding-tutorial-on-visualization</code>.
</p>
</li>
<li>
<p>
Submit a pull request by clicking the ‘New pull request’ button, right next to the branch dropdown.
</p>
</li>
</ol>
<p>
If it is easier for you to send them to us some other way, please mail us at <a href="mailto:authorcarpentry@library.caltech.edu">authorcarpentry@library.caltech.edu</a>. Given a choice between you creating content or wrestling with Git, we’d rather have you doing the former.
</p>
<h2 id="locations-and-formats">
Locations and Formats
</h2>
<p>
Every lesson has a repository of its own, while individual topics are files in that directory. For example, the <code>shell-ecology</code> directory holding our introduction to the shell for ecology contains the files <code>00-intro.md</code>, <code>01-filedir.md</code> and so on. (We use two digits followed by a one-word topic key to ensure files appear in the right order when listed.)
</p>
<h2 id="formatting-of-the-material">
Formatting of the material
</h2>
<p>
To ensure a consistent formatting of the lessons, we recommend the following guidelines:
</p>
<ul>
<li>
No trailing white space
</li>
<li>
Wrap lines at 80 characters (unless it breaks URLs)
</li>
</ul>
<h2 id="faq">
FAQ
</h2>
<p>
<em>Where can I get help?</em>
</p>
<p>
Mail us at <a href="mailto:authorcarpentry@library.caltech.edu">authorcarpentry@library.caltech.edu</a>
</p>
</section>
<footer>
<span>© Author Carpentry</span>
<span><a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img
alt="Creative Commons License" style="vertical-align: middle;"
src="https://i.creativecommons.org/l/by/4.0/80x15.png" /></a></span>
<span>This work is licensed under a <a rel="license"
href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution
4.0 International License</a></span>
</footer>
</body>
</html>