Contributing to the Database Systems Lecture Notes

February 1, 2024 (02:15:02 PM)

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

You can find a brief presentation of those notes on their website. They are the main source of exercises, problems and notes for a Database class taught at Augusta University, 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

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 for a list of known bugs and possible improvements.

How to Contribute

You can

Note that your contribution will be placed under the CC BY 4.0 licence: refer to LICENSE.md for more details. If you would like to directly edit the code and submit a pull request, please follow the workflow and guidelines detailed below.

Workflow

Cloning, Installing and Compiling

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

Editing

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

  1. Pull
  2. Edit
  3. Commit
  4. 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 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 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

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). The syntax is rendered using the <dd> and <dt> tags in htmland is as follows.

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

Solution +.#

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

Not in the solution anymore

will produce

Solution 4.1

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

Not in the solution anymore

Block environment are typed using

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

.
├── 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.

Code Files Naming Convention

Java

  1. All the java code is beautified by the google-java-format program shared in the lib subfolder (cf. the clean_java macro in the makefile).
  2. Every JAVA file name will be written as UpperCamelCase.
  3. Words are smashed together and the first letter of each word is capitalized. No word separator, like the underscore _, is used.

Example

FileName.java
  1. If there is any version/number, it should be written as,
FileName0#. java, FileName0#. java

Classes and Interfaces Names

  1. Class and interface names are generally noun or noun phrases.
  2. Class and interface must begin with a capital letter.

Example

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

Method Names

  1. Method names generally begin with a lowercase letter.
  2. 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

public void setTitle(String t) { ... }
  1. A function call yields a value, so a function name is generally a noun phrase that describes the value.

Example

public double areaOfTriangle(int b, int c, int d) { ... }
  1. The name of a boolean function is often a verb phrase starting with “is”, thus describing what the value means,

Example

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

Variable Names

  1. Variable names generally start with a lowercase letter.
  2. Variable names should give the reader some hint about what the variable is used for.
  3. 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.
  4. 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.
  5. There is a tension between writing long descriptive names and very short names.
  6. We tend to use shorter names for parameters and local variables and longer names for fields and static variables.

Parameter Names

  1. Parameter names may be short, even one letter long.

Example

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

Local variable names

  1. A local variable is a variable that is declared in a method body.
  2. Its declaration should be placed as close to its first use as possible.
  3. 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

  1. The meaning of fields and class variables are typically given as comments by the declarations, far from where the variables are used.
  2. 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

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

Comment Style(s):

  1. Documentation comments- These describe classes, methods, content, etc. Usually placed before declarations.

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

    // This is a comment.
  3. Multi-line comments- Used for large text that span across multiple lines

    /*
     * This is a comment that
     * is multiple lines long.
     */
    Spacing:
  • Use two spaces for each indent, conforming to the guide in use.

SQL

  1. All the SQL code is beautified by the pg_format program (cf. the clean_sql macro in the makefile).
  2. All the SQL code is tested using the code/sql/validate.sh macro.
  3. Every file is named after the schema, and every schema starts with HW_.

Example

HW_SchemaName.sql

Comment Style(s):

  1. Single line comments

    -- This is a comment.
  2. Multi-line comments

    /*
    This is a comment that
    is multiple lines long.
    */

Spacing:

  • Use two spaces for each indent

XML

  • XML Files in Code Folder
  1. Camel case is a common naming rule in JavaScripts.
  2. Uppercase first letter in each word except the first. #### Example > firstName.xml

Comment Style(s):

<!-- Single line -->
<!--
    Multi-line
    Comment
 -->

Spacing:

  • Use four spaces for each indent

CSS

Comment Style(s):

W3C specifications says to define comments using /* ... */ whether single or multi-line because // isn’t supported on all browsers and can cause unexpected results.

Spacing:

  1. Use four spaces for each indent
  2. Add one empty line between style definitions Example:
.class {
    property: value;
}

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

Text

  • Titles are capitalized using the Chicago Manual:
  1. Capitalize the first and the last word.
  2. Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
  3. Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.
  4. Lowercase the ‘to’ in an infinitive (I want to play guitar).
  • Please, keep in mind that, as (Knuth, Larrabee, and Roberts 1989, 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

  1. Make file names lowercase.
  2. Separate words with underscores.
  3. Use only standard ASCII alphanumeric characters in file and directory names.

Folder Name

  1. Folder Name should be meaningful.
  2. 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

  1. Figures Names should follow the Underscore Case.
  2. Everything is in lower case and the words are separated by underscores.
  3. 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:

Knuth, Donald E., Tracy Larrabee, and Paul M. Roberts. 1989. Mathematical Writing. MAA Notes. Mathematical Association of America.