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

Please refer to <https://spots.augusta.edu/caubert/db/ln/README.html#authors-and-contributors> for a detail of the past contributions.
This document focuses on explaining how to contribute to those 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](https://spots.augusta.edu/caubert/db/ln/).
They are the main source of exercises, problems and notes for a [Database class](https://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. <https://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.

[The example file](../notes/example.html) is a gentle introduction to the syntax used in this document.


##   Naming Convention Rules

>#### *A collection of guidelines for writing file, folder, classes, figures, and images names in the project. These guidelines should help you toward that goal of not only correct code, but understandable.*

* Our working directory is


~~~{.plain}
.
├── install/                -- Installing the requirements to compile the document.
├── notes/                  -- The notes themselves.
│   ├── bib/                -- References (including reference to the document).
│   ├── code/               -- Source code included in the document.
│   ├── fig/                -- Source code for various figures used in the document.
│   ├── filters/            -- Pandoc filters.
│   ├── img/                -- Various image files integrated in the document.
│   ├── latex/              -- Latex configuration file.
│   ├── lib/                -- Various libraries
│   ├── style/              -- css style and auxiliary files for the web page.
│   ├── lectures_notes.md   -- The main file for the lecture notes.
│   ├── Makefile            -- Directives to generate the lecture notes.
│   └── temp.md             -- Temporary file, for debugging purposes.
├── CONTRIB.md              -- A guide on how to contribute.
├── KNOWN_BUGS.md           -- A list of possible bugs and improvements.
├── LICENSE.md              -- The license of those notes.
├── README.md               -- The present file.
└── WORKFLOW.md             -- An step-by-step guide on how to edit those notes.
~~~
* We want to follow some Naming Convention Rules, specifically on the following objects.

  * Code Files
    * Java
    * SQL
    * XML
  * Text in the Document
  * Files
  * Folders
  * Bibtex

## Code Files Naming 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).
#.  Every JAVA file name will be written as UpperCamelCase.
#.  Words are smashed together and the first letter of each word is capitalized. No word separator, like the underscore _, is used.

#### Example

```{.plain}
FileName.java

```

#. If there is any version/number, it should be written as,

```{.plain}
FileName0#. java, FileName0#. java
```

####  Classes and Interfaces Names
#.  Class and interface names are generally noun or noun phrases.
#.  Class and interface must begin with a capital letter.

#### Example

```{.java}
interface AqueousHabitat { ... }
class FishBowl implements AqueousHabitat { ... }
```

#### Method Names

#.  Method names generally begin with a lowercase letter.
#.  A call on a procedure is a statement to do something, so a procedure name is generally a verb phrase that is a command to do something.

#### Example

```{.java}
public void setTitle(String t) { ... }
```

#.  A function call yields a value, so a function name is generally a noun phrase that describes the value.

#### Example

```{.java}
public double areaOfTriangle(int b, int c, int d) { ... }
```

#. The name of a boolean function is often a verb phrase starting with "is", thus describing what the value means,

#### Example

```{.java}
public boolean isEquilateralTriangle(int b, int c, int d) { ... }
```

#### Variable Names
#.    Variable names generally start with a lowercase letter.
#.    Variable names should give the reader some hint about what the variable is used for.
#.    A well-chosen name, which gives a hint at the meaning of the variable, helps document a program, making it easier to understand. On the other hand, using the names of your friends or flowers that you like as variable names just annoys and makes the program harder to understand. Don't do that.
#.    Also, refrain from using vague names like counter or var or data; instead think about what the variable really is for and use a more concrete name.
#.    There is a tension between writing long descriptive names and very short names.
#.    We tend to use shorter names for parameters and local variables and longer names for fields and static variables.

#### Parameter Names
 #.  Parameter names may be short, even one letter long.

#### Example

```{.java}
public boolean isEquilateralTriangle(int b, int c, int d) {return b == c && c == d;}
```

#### Local variable names
#. A local variable is a variable that is declared in a method body.
#. Its declaration should be placed as close to its first use as possible.
#. The scope of a local variable is usually short, and its meaning is often obvious either from a comment on its declaration or from the short code in which it is used. Therefore, names of local variables may be short.

#### Fields and class (i.e. static) variables
#.  The meaning of fields and class variables are typically given as comments by the declarations, far from where the variables are used.
#.  Therefore, the names of field and class variables should be longer and as mnemonic as possible, giving the reader a good idea what the meaning are.

#### Package names
  #. Package names are usually all lowercase and consist of nouns.


#### 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
#. All the SQL code is beautified by the [pg_format](https://github.com/darold/pgFormatter) program (cf. the `clean_sql` macro in the makefile).
#. All the SQL code is tested using the `code/sql/validate.sh` macro.
#. Every file is named after the schema, and every schema starts with HW_.

#### Example

```{.plain}
HW_SchemaName.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 two spaces for each indent


### XML

* XML Files in Code Folder
#.  Camel case is a common naming rule in JavaScripts.
#.  Uppercase first letter in each word except the first.
#### Example
>   firstName.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

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

### File Name
#.   Make file names lowercase.
#.   Separate words with underscores.
#.   Use only standard ASCII alphanumeric characters in  file and directory names.


### Folder Name
#.  Folder Name should be meaningful.
#.  Make folder names lowercase.

### Bibtex Entries

Entries are formatted using the on-line service <https://flamingtempura.github.io/bibtex-tidy/>, using four spaces for each indent and aligning values.

### Figure Name

#.  Figures Names should follow the Underscore Case.
#.  Everything is in lower case and the words are separated by underscores.
#.  This convention is also popularly known as snake case.

#### Example
>  figure_name.svg
>

### *Important* Notes:

*   Do not use names which could misguide other developers.
*   Names should be meaningfully distinct and pronounceable.



# References {-}

Inspirations:

  *  <https://www.geeksforgeeks.org/.>
  *  <https://www.w3schools.com/xml/xml_elements.asp.>
  *  <https://developers.google.com/style/filenames.>
  *  <https://guides.lib.purdue.edu/c.php?g=353013&p=2378293>
  *  <https://dev.to/danialmalik/a-beginner-s-guide-to-clean-code-part1-naming-conventions-139l>
  *  <https://www.cs.cornell.edu/courses/JavaAndDS/JavaStyle.html>