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.
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/.
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!
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.
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.
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.
Common practice of workflow when working with other contributors on a repository includes these steps, in order:
Before editing any file, make sure you have the latest version of the notes, by pulling the source.
git pull
. This will fetch and download content
from the remote repository and update your local repository.git stash
git pull
git stash pop
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.You can edit any file or add some, preferably following the guidelines below.
Before you commit, you need to stage your files. Staging a file is to simply prepare it for a commit.
git add --all
, in the command-line
interface where the working directory is the folder containing the
notes.git commit -m "Short meaningful comment of what you did here"
git commit -a -m "Short meaningful comment of what you did here"
.Now, you can push your modification to the remote repository.
git push
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 html
and 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.
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.
We want to follow some Naming Convention Rules, specifically on the following objects.
lib
subfolder (cf. the
clean_java
macro in the makefile).FileName.java
FileName0#. java, FileName0#. java
interface AqueousHabitat { ... }
class FishBowl implements AqueousHabitat { ... }
public void setTitle(String t) { ... }
public double areaOfTriangle(int b, int c, int d) { ... }
public boolean isEquilateralTriangle(int b, int c, int d) { ... }
public boolean isEquilateralTriangle(int b, int c, int d) {return b == c && c == d;}
clean_sql
macro in the makefile).code/sql/validate.sh
macro.HW_SchemaName.sql
Single line comments
-- This is a comment.
Multi-line comments
/*
This is a comment that
is multiple lines long.
*/
<!-- Single line -->
<!--
Multi-line
Comment
-->
W3C specifications says to define comments using /* ... */
whether
single or multi-line because //
isn’t supported
on all browsers and can cause unexpected results.
.class {
: value;
property
}
.another-class {
: value;
property }
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.
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.svg
Inspirations:
Comment Style(s):
Documentation comments- These describe classes, methods, content, etc. Usually placed before declarations.
Single line comments- Allows narrative on one line at a time
Multi-line comments- Used for large text that span across multiple lines
Spacing: