---
title: Contributing to the Database Systems Lecture Notes
---

# Contributing

We are really glad you are reading this, because we need students, volunteers and contributors (at all level!) to improve this project.
If you are not familiar with the open source eco-system and how you can help projects in general, you can have a look at <https://opensource.guide/>.

# About the Project {#about}

You can find a brief presentation of those notes [on their website](http://spots.augusta.edu/caubert/db/ln/).
They are the main source of exercises, problems and notes for a [Database class](http://spots.augusta.edu/caubert/db/) taught at [Augusta University](https://www.augusta.edu/), and are updated every time the class is taught.
Improving the content of those notes by your suggestions, remarks and questions _will_ benefit students and instructors, so don't be shy!

# What to Contribute {#what}

Your contribution can take multiple forms.
Did you find a bug, a mistake, a typo?
Do you have a question about the source code?
Whenever it is an open-ended question, a nitpicking comment or a request for content, all contributions are welcome and will be answered.

If you'd like to contribute but are not sure where to start, you can refer to [`KNOWN_BUGS.md`](KNOWN_BUGS.html) for a list of known bugs and possible improvements.

# How to Contribute {#how}

You can 

- …contact or visit the main author, cf. <http://spots.augusta.edu/caubert/#contact>.
- …submit bug reports at <https://rocketgit.com/user/caubert/CSCI_3410/bug> (requires an account).
- …submit a pull request, which is the way detailed below.

Note that your contribution will be placed under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) licence: refer to [`LICENSE.md`](LICENSE.html) for more details.
If you would like to directly edit the code and submit a pull request, please follow the [workflow](#workflow) and [guidelines](#guidelines) detailed below.

## Workflow {#workflow}

### Cloning, Installing and Compiling {#pre-req}

Please refer to [install/INSTALL.md](install/INSTALL.html) for a complete guide on how to clone the source code, install the required software and compile those notes.

### Editing {#editing}

Common practice of workflow when working with other contributors on a repository includes these steps, in order:

#. Pull
#. Edit
#. Commit
#. Push / Creating a pull request

#### Pulling

Before editing any file, make sure you have the latest version of the notes, by pulling the source.

* Open a command-line interface (or "Terminal") and make the folder containing the notes the current working directory.
* Type `git pull`.
  This will fetch and download content from the remote repository and update your local repository.
* If you run into merge conflicts:
    * If you need to save your files before a pull, execute these commands in order:
        * `git stash`
        * `git pull`
        * `git stash pop`
    * If `git pull` refuses to overwrite your change, to reset to the HEAD commit, type:
      `git reset --hard origin/ master`. This will erase any local changes you've made and restore the repository
       to its last working commit.

#### Editing

You can edit any file or add some, preferably following the [guidelines](#guidelines) below.

#### Commiting

Before you commit, you need to stage your files. Staging a file is to simply prepare it for a commit.

* As before, open a command-line interface (or "Terminal") and make the folder containing the notes the current working directory.
* You may customize the files you choose to commit but simplest way is to commit all your changes. To commit all changes made from your local repository, type: `git add --all`, in the command-line interface where the working directory is the folder containing the notes.
* Now, your repository is ready to be committed. Type: `git commit -m "Short meaningful comment of what you did here"`
* You can combine those last two commands into one, using `git commit -a -m  "Short meaningful comment of what you did here"`.

#### Pushing / Creating a pull request

Now, you can push your modification to the remote repository.

* As before, open a command-line interface (or "Terminal") and make the folder containing the notes the current working directory.
* Type: `git push`
* And … that's it! [Rocketgit](https://rocketgit.com/op/features/anonpush) implements a simple way to perform anonymous pushes, so that without account nor right on the repository, you can simply and freely submit your contribution to the repository!

## Guidelines {#guidelines}

If you want to learn markdown, which is the language used to write those notes, refer to e.g. <https://commonmark.org/help/>.
As pandoc is used to convert this document, it is "pandoc-flavored markdown"---which is fairly standard---that is used.

Probably the main oddity comes from the the Solution, Problem and Exercises environments (numbered using [pandoc-numbering](https://github.com/chdemko/pandoc-numbering)).
The syntax is rendered using the `<dd>` and `<dt>` tags in `html`and is as follows.

We can either have in-line, or block, environment.
For in-line, using

```markdown
Solution +.#

: Solution on one line.
We are still on the same line.

Not in the solution anymore
```

will produce

> Solution +.#
> 
> : Solution on one line.
> We are still on the same line.
> 
> Not in the solution anymore

Block environment are typed using 

```md
Solution +.#
~ 
    Solution on a block.
    Still in the block.

    Still in the block, on a different paragraph.

Not in the solution anymore
```

and those will produce

> Solution +.#
> ~ 
>     Solution on a block.
>     Still in the block.
>
>     Still in the block, on a different paragraph.
>
> Not in the solution anymore

The indentation makes all the difference in the block environment.

### Text

- Titles are capitalized using the Chicago Manual:

> - Capitalize the first and the last word.
> - Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
> - Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.
> - Lowercase the ‘to’ in an infinitive (I want to play guitar).

- Please, keep in mind that, as [@knuth1989mathematical, p. 19] writes:
    
    > Exercises are some of the most difficult parts of a book to write. Since an exercise has very little context, ambiguity can be especially deadly; a bit of carefully chosen redundancy can be especially important.

    
### Code Convention

#### Java 
All the java code is beautified by the [google-java-format](https://github.com/google/google-java-format/) program shared in the `lib` subfolder (cf. the `clean_java` macro in the makefile).
##### Comment Style(s):
#. Documentation comments- These describe classes, methods, content, etc. Usually placed before declarations.

    ```{.java}
    /**
     * This is a comment describing
     * the code/content placed after this.
     */
    ```
#. Single line comments- Allows narrative on one line at a time

    ```{.java}
    // This is a comment.
    ```
#. Multi-line comments- Used for large text that span across multiple lines

    ```{.java}
    /*
     * This is a comment that
     * is multiple lines long.
     */
    ```
##### Spacing:
* Use two spaces for each indent, conforming to the [guide in use](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation).

#### SQL
##### Comment Style(s):
#. Single line comments
	```{.sql}
    -- This is a comment.
    ```
#. Multi-line comments
	```{.sql}
    /*
	This is a comment that
	is multiple lines long.
    */
    ```

##### Spacing:
* Use four spaces for each indent


#### XML
##### Comment Style(s):
	```{.xml}
	<!-- Single line -->
	```
	```{.xml}
	<!--
		Multi-line
		Comment
	 -->
	```

##### Spacing:
* Use four spaces for each indent

#### CSS
##### Comment Style(s):
W3C specifications says to define comments using ```/* ...  */```{.css} whether single or multi-line because ```//```{.css} isn't supported on all browsers and can cause unexpected results.
##### Spacing:
* Use four spaces for each indent
* Add one empty line between style definitions
Example:
	```{.css}
	.class {
	property: value;
	}

	.another-class {
	property: value;
	}
	```
* Add a space after colons between properties and values

# References {-}