Skip to content

Commit 08e6801

Browse files
jbelmontjbelmont
committed
Add github templates and new page and a contributing markdown file.
1 parent e44b9d9 commit 08e6801

9 files changed

+258
-1
lines changed

‎.github/ISSUE_TEMPLATE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Before submitting, please explain where the bug is in the repository and any steps to reproduce the issue.

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!--
2+
Thank you for your pull request. Please provide a description above and review
3+
the requirements below.
4+
5+
Contributors guide: https://github.com/jbelmont/blob/master/CONTRIBUTING.md
6+
-->
7+
8+
##### Checklist
9+
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->
10+
11+
- [ ] documentation is changed or added
12+
- [ ] script changes are made

‎CONTRIBUTING.md

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Contributing to Unix Programming and Regular Expressions Workshop
2+
3+
Contributions to this workshop may come in many forms. Some contribute code changes,
4+
others contribute docs.
5+
6+
No contribution is too small and all contributions are valued.
7+
8+
This guide details the basic steps for getting started contributing to the unix workshop GitHub Repository and describes what to expect throughout each step of the process.
9+
10+
## Submitting a Pull Request
11+
12+
#### Setting up your local environment
13+
14+
To get started, you will need to have `git` installed locally. Depending on
15+
your operating system, there are also a number of other dependencies required.
16+
17+
Once you have `git` and are sure you have all of the necessary dependencies,
18+
it's time to create a fork.
19+
20+
Before getting started, it is recommended to configure `git` so that it knows
21+
who you are:
22+
23+
```text
24+
$ git config --global user.name "John Rambo"
25+
$ git config --global user.email "[email protected]"
26+
```
27+
Please make sure this local email is also added to your
28+
[GitHub email list](https://github.com/settings/emails) so that your commits
29+
will be properly associated with your account and you will be promoted
30+
to Contributor once your first commit is landed.
31+
32+
#### Step 1: Fork
33+
34+
Fork the project [on GitHub](https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop) and clone your fork locally.
35+
36+
![Fork Project](images/fork.png)
37+
38+
When the fork is complete you will see the following screen
39+
40+
![My Forked Project](images/myfork.png)
41+
42+
```text
43+
$ git clone [email protected]:jbelmont/unix-programming-and-regular-expressions-workshop.git
44+
$ cd unix-programming-and-regular-expressions-workshop
45+
$ git remote add upstream https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop.git
46+
$ git fetch upstream
47+
```
48+
49+
#### Step 2: Branch
50+
51+
As a best practice to keep your development environment as organized as
52+
possible, create local branches to work within. These should also be created
53+
directly off of the `master` branch.
54+
55+
```text
56+
$ git checkout -b my-branch -t upstream/master
57+
```
58+
59+
#### The Process of Making Changes
60+
61+
###### Editing Files
62+
63+
This workshop has markdown files in the *docs* folder.
64+
65+
If you want to edit any doc files for the repository please do so in *docs* folder
66+
67+
For example if you wanted to fix errors in the `docs/history-substitution.md` then you would make document changes inside there.
68+
69+
###### Adding Files
70+
71+
The workshop has a corresponding Gitbook that is built using [Gitbook](https://toolchain.gitbook.com/)
72+
73+
If you add a *markdown file* in the _docs_ folder then you will need to update the *SUMMARY.md*
74+
75+
Contents of the *SUMMARY.md*
76+
77+
```markdown
78+
## Unix Programming and Regular Expressions Workshop
79+
80+
* [Workshop Introduction](/README.md)
81+
* [Basics of Shell Programming](docs/basics-of-shell-programming.md)
82+
* [Introduction to Text Processing](docs/introduction-to-text-processing.md)
83+
* [Text Searching](docs/text-searching.md)
84+
* [Text Substitution](docs/text-substitution.md)
85+
* [Filename expansions and globbing](docs/filename-expansions-and-globbing.md)
86+
* [Working with Fields](docs/working-with-fields.md)
87+
* [Text Sorting](docs/text-sorting.md)
88+
* [Arithmetic Operations and variables](docs/arithmetic-operations-and-variables.md)
89+
* [Decision Making and Exit Status](docs/decision-making-and-exit-status.md)
90+
* [Looping](docs/looping.md)
91+
* [Input and Output](docs/input-and-output.md)
92+
* [Command Process Substitution](docs/command-process-substitution.md)
93+
* [History Substitution](docs/history-substitution.md)
94+
* [Evaluation Order](docs/evaluation-order.md)
95+
* [Subshells](docs/subshells.md)
96+
* [Shell Functions](docs/shell-functions.md)
97+
* [Signal Handling](docs/signal-handling.md)
98+
* [Working with Files](docs/working-with-files.md)
99+
* [Building Command line applications](docs/building-command-line-applications.md)
100+
```
101+
102+
When you add a file to the docs folder you will need to add the entry into the file above and the logical order you think it would go into. The easiest way to do to that is to copy one of the lines and edit Name and path.
103+
104+
Don't worry about generating the *Gitbook* once you have edited the docs file or you have added a new docs file and you have submitted your Pull Request and it is merged into master, I will do the following on my part.
105+
106+
My steps that you don't have to worry about:
107+
108+
1. Merge your Pull Request
109+
2. Run `git pull` in my local branch
110+
3. If you added a new file I will run the following script to update *Gitbook* Site
111+
1. `npm run docs:publish`
112+
113+
*package.json file*:
114+
115+
```json
116+
{
117+
"name": "unix-programming-and-regular-expressions-workshop",
118+
"version": "1.0.0",
119+
"description": "A workshop on Unix Programming Principles using tools such as grep, sed, awk, shell programming and regular expressions",
120+
"main": "index.js",
121+
"scripts": {
122+
"docs:prepare": "gitbook install",
123+
"docs:build": "npm run docs:prepare && rm -rf _book && gitbook build",
124+
"docs:watch": "npm run docs:prepare && gitbook serve",
125+
"docs:publish": "npm run docs:build && cd _book && git init && git commit --allow-empty -m 'Update docs' && git checkout -b gh-pages && touch .nojekyll && git add . && git commit -am 'Update docs' && git push [email protected]:jbelmont/unix-programming-and-regular-expressions-workshop.git gh-pages --force"
126+
},
127+
"repository": {
128+
"type": "git",
129+
"url": "git+https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop.git"
130+
},
131+
"keywords": [],
132+
"author": "Jean-Marcel Belmont <[email protected]>",
133+
"license": "MIT",
134+
"bugs": {
135+
"url": "https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop/issues"
136+
},
137+
"homepage": "https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop#readme",
138+
"devDependencies": {
139+
"gitbook": "^3.2.3",
140+
"gitbook-cli": "^2.3.2"
141+
}
142+
}
143+
```
144+
145+
You won't be able to run `npm run docs:publish` unless I give you admin rights to the repo but essentially I force push changes to github pages and the static website gets regenerated.
146+
147+
Notice that there is a script called **docs:publish* in the *scripts* section of *package.json*
148+
149+
##### Commit message guidelines
150+
151+
A good commit message should describe what changed and why.
152+
153+
1. The first line should:
154+
- contain a short description of the change
155+
- be 50 characters or less
156+
- be entirely in lowercase with the exception of proper nouns, acronyms, and
157+
the words that refer to code, like function/variable names
158+
159+
2. Keep the second line blank.
160+
3. Wrap all other lines at 72 columns.
161+
162+
4. If your patch fixes an open issue, you can add a reference to it at the end
163+
of the log. Use the `Fixes:` prefix and the full issue URL.
164+
165+
Examples:
166+
- `Fixes: https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop/issues/10`
167+
168+
Sample complete commit message:
169+
170+
```txt
171+
Body of commit message is a few lines of text, explaining things
172+
in more detail, possibly giving some background about the issue
173+
being fixed, etc.
174+
175+
The body of the commit message can be several paragraphs, and
176+
please do proper word-wrap and keep columns shorter than about
177+
72 characters or so. That way, `git log` will show things
178+
nicely even when it is indented.
179+
180+
Fixes: https://github.com/jbelmont/unix-programming-and-regular-expressions-workshop/issues/10
181+
```
182+
183+
#### Step 5: Rebase
184+
185+
As a best practice, once you have committed your changes, it is a good idea
186+
to use `git rebase` (not `git merge`) to synchronize your work with the main
187+
repository.
188+
189+
```text
190+
$ git fetch upstream
191+
$ git rebase upstream/master
192+
```
193+
194+
This ensures that your working branch has the latest changes from `nodejs/node`
195+
master.
196+
197+
#### Step 7: Push
198+
199+
Once you are sure your commits are ready to go, begin the process of opening a Pull Request by pushing your working branch to your fork on GitHub.
200+
201+
```text
202+
$ git push origin my-branch
203+
```
204+
205+
#### Step 8: Opening the Pull Request
206+
207+
From within GitHub, opening a new Pull Request will present you with a template
208+
that should be filled out:
209+
210+
```markdown
211+
<!--
212+
Thank you for your pull request. Please provide a description above and review
213+
the requirements below.
214+
215+
Contributors guide: https://github.com/jbelmont/blob/master/CONTRIBUTING.md
216+
-->
217+
218+
##### Checklist
219+
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->
220+
221+
- [ ] documentation is changed or added
222+
- [ ] script changes are made
223+
```
224+
225+
Please try to do your best at filling out the details, but feel free to skip
226+
parts if you're not sure what to put.
227+
228+
Once opened, Pull Requests are usually reviewed within a few days.

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ A workshop on Unix Programming Principles using tools such as grep, sed, awk, sh
2525
* [Shell Functions](docs/shell-functions.md)
2626
* [Signal Handling](docs/signal-handling.md)
2727
* [Working with Files](docs/working-with-files.md)
28+
* [Remote File Sharing and File Access](docs/remote-file-sharing-and-file-access.md)
2829
* [Building Command line applications](docs/building-command-line-applications.md)
2930

3031
## Unix History

‎SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,5 @@
1919
* [Shell Functions](docs/shell-functions.md)
2020
* [Signal Handling](docs/signal-handling.md)
2121
* [Working with Files](docs/working-with-files.md)
22+
* [Remote File Sharing and File Access](docs/remote-file-sharing-and-file-access.md)
2223
* [Building Command line applications](docs/building-command-line-applications.md)

‎docs/building-command-line-applications.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ _________________________
1111

1212
Previous | Next
1313
:------- | ---:
14-
← [Working with Files](./working-with-files.md) | [README](../README.md) →
14+
← [Remote File Sharing and File Access](./remote-file-sharing-and-file-access.md) | [README](../README.md) →

‎docs/remote-file-sharing-and-file-access.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## Unix Programming and Regular Expressions Workshop - Remote File Sharing and File Access
2+
3+
## Sections:
4+
5+
* [Bread Crumb Navigation](#bread-crumb-navigation)
6+
7+
Content
8+
9+
#### Bread Crumb Navigation
10+
_________________________
11+
12+
Previous | Next
13+
:------- | ---:
14+
← Working with Files](./working-with-files.md) | [Building Command line applications](./building-command-line-applications.md) →

‎images/fork.png

68.8 KB
Loading

‎images/myfork.png

131 KB
Loading

0 commit comments

Comments
 (0)