Skip to content

Commit 1f8c5c4

Browse files
committed
Added more documentation
As the project needs more documentation and the README file itself is not as full, this commit is adding many different files that help the project. It is adding a CITATION.cff file that allows the user to directly use the citation feature in GitHub and does not need to set up the citation themselves. Added a CONTRIBUTING.md file that writes down many things that people need to know, when they want to contribute to the project. Edited extension.json where `special` is replaced with `custom` as `custom` sounds more formal and more fitting to the project. Edited README.md and replaced `special` with `custom` as `custom` sounds more formal and more fitting to the project. - Added more information about what is generated by the MultiCodeBlock project. - Added the Benefits about why the MultiCodeBlock extension is useful. - Added the full Apache-2.0 license at the bottom of the file.
1 parent 51e9141 commit 1f8c5c4

File tree

4 files changed

+351
-3
lines changed

4 files changed

+351
-3
lines changed

CITATION.cff

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# YAML 1.2
2+
---
3+
abstract: "A codeblock consisting of multiple languages and different codesnippets in this langauge and a custom way of commenting the code."
4+
authors:
5+
-
6+
family-names:
7+
given-names: QuickWrite
8+
cff-version: "1.1.0"
9+
date-released: 2021-07-31
10+
keywords:
11+
- PHP
12+
- Codeblock
13+
- MediaWiki
14+
- "MediaWiki-Extension"
15+
license: "Apache-2.0"
16+
message: |
17+
"If you use this software, please cite it using these metadata.
18+
You could use your own citation, but this is in many cases easier to use."
19+
title: MultiCodeBlock
20+
version: "0.1.0"
21+
...

CONTRIBUTING.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# How to contribute to MultiCodeBlock
2+
First off, thanks for taking the time to contribute!
3+
4+
#### How to install MultiCodeBlock
5+
1. Clone the repository through Git
6+
2. Put it inside the extensions folder in your own MediaWiki installation
7+
3. Install the necessary dependencies through `composer install` in the `includes/` folder.
8+
9+
#### **Did you find a bug?**
10+
11+
* **Do not open up a GitHub issue if the bug is an issue
12+
in PHP or MediaWiki**, and instead open an issue in one of their respective bug trackers.
13+
* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/QuickWrite/MultiCodeBlock/issues).
14+
* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/QuickWrite/MultiCodeBlock/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring.
15+
* If possible, use the relevant bug report templates to create the issue.
16+
17+
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
18+
19+
#### How Do I Submit A (Good) Bug Report?
20+
21+
Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined [which repository](#atom-and-packages) your bug is related to, create an issue on that repository and provide the following information by filling in [the template](https://github.com/atom/.github/blob/master/.github/ISSUE_TEMPLATE/bug_report.md).
22+
23+
Explain the problem and include additional details to help maintainers reproduce the problem:
24+
25+
* **Use a clear and descriptive title** for the issue to identify the problem.
26+
* **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, **don't just say what you did, but explain how you did it**.
27+
* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
28+
* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
29+
* **Explain which behavior you expected to see instead and why.**
30+
* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem.
31+
* **If you're reporting that MediaWiki crashed because of MultiCodeBlock**, include a crash report with a stack trace from the operating system. Include the crash report in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist.
32+
* **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below.
33+
34+
#### **Did you write a patch that fixes a bug?**
35+
36+
* Open a new GitHub pull request with the patch.
37+
* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
38+
39+
#### **Suggesting Enhancements**
40+
This section guides you through submitting an enhancement suggestion for Atom, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion 📝 and find related suggestions 🔎.
41+
You should suggest your idea as a [GitHub Issue](https://github.com/QuickWrite/MultiCodeBlock/issues/new).
42+
43+
* **Use a clear and descriptive title** for the issue to identify the suggestion.
44+
* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
45+
* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
46+
* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
47+
* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of MultiCodeBlock which the suggestion is related to.
48+
* **Explain why this enhancement would be useful** to most users and isn't something that can or should be implemented as a different extension.
49+
* **Specify which version of MultiCodeBlock you're using.**
50+
* **Specify the name and version of the OS you're using.**
51+
52+
#### Styleguide
53+
If you are planning to commit any changes to the project, it would be highly appreciated if you were to follow the project code style conventions.
54+
55+
All of the code must be indented by tabs and curly brackets must be set in the compact style.
56+
57+
PHP:
58+
```php
59+
/**
60+
* Functions should be documented in the PHPDocumentor standard.
61+
*/
62+
function example() {
63+
// Strings should always be '', except when they should have extra functions inside them.
64+
echo 'This is an example!';
65+
}
66+
```
67+
68+
CSS:
69+
```css
70+
/* There are no real comment guides */
71+
style {
72+
/* Even though it is possible to leave the last seimcolon out, it shouldn't be done */
73+
display: block;
74+
}
75+
```
76+
77+
JavaScript:
78+
```javascript
79+
// Variables should always be let or const
80+
let counter = 0;
81+
82+
// Semicolons must be set after each statement.
83+
document.getElementById('myid').addEventListener('click', () => {
84+
console.log(counter);
85+
86+
counter++;
87+
});
88+
```
89+
90+
#### Thanks!
91+
Thanks for reading the *CONTRIBUTING* file and helping the project!

0 commit comments

Comments
 (0)