Skip to content

Commit cacb288

Browse files
GiulioCosentinoGiulioCosentino
committed
Merge branch 'structure'
2 parents 3b42072 + 4792870 commit cacb288

File tree

7 files changed

+534
-502
lines changed

7 files changed

+534
-502
lines changed

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
// Draw.io
1212
"hediet.vscode-drawio.simpleLabels": true,
1313

14+
// Markdown
15+
"markdown.extension.toc.updateOnSave": false,
16+
1417
// LaTeX
1518
"latex-workshop.latex.outDir": "%DIR%/build/",
1619
"latex-workshop.latex.rootFile.useSubFile": true,

‎CONTRIBUTING.md‎

Lines changed: 175 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,210 @@
1-
# Contributing to the Notes repository
1+
# Contributing
2+
3+
**Thank you for considering contributing to this repository!**
4+
5+
- [🤝 Ways of contributing](#-ways-of-contributing)
6+
- [✍️ How to create new notes](#-how-to-create-new-notes)
7+
- [Workspace setup](#workspace-setup)
8+
- [Notes directory](#notes-directory)
9+
- [🔄 Repository workflow](#-repository-workflow)
10+
- [Branches](#branches)
11+
- [Merges](#merges)
12+
- [Roles](#roles)
13+
- [Commits](#commits)
14+
15+
## 🤝 Ways of contributing
16+
17+
✍️ **Create new notes**: see the [section below](#-how-to-create-new-notes).
18+
19+
🔧 **Improve existing ones**: fork the repository and create a pull request.
20+
21+
❗**Report errors** or 💡**make suggestions**:
22+
23+
- [Contact the project manager](README.md#-contact), or
24+
- [Create a GitHub Issue](https://github.com/MuNuChapterHKN/Eta-Kappa-Notes/issues/new), or
25+
- Fork the repository and create a pull request
26+
27+
## ✍️ How to create new notes
28+
29+
### Workspace setup
30+
31+
1. Choose a course for which you will take notes.
32+
2. [Tell the project manager](README.md#-contact)
33+
3. The project manager will create a branch and tell you to fork it.
34+
35+
### Notes directory
36+
37+
Inside `notes/`:
38+
- delete the `.gitkeep` file;
39+
- create a folder `<notes-name>/` with the same name as your branch.
40+
41+
From this points on, this guide only applies to LaTeX notes.
42+
43+
You will organize your notes inside it using the following structure:
44+
45+
<!-- https://asciitools.com/tree?trailingDirSlash=true&fullPath=false&rootDot=false -->
46+
notes/
47+
└── notes-name/
48+
├── chapters/
49+
├── res/
50+
│ ├── drawio/
51+
│ ├── ggb/
52+
│ ├── py/
53+
│ ├── svg/
54+
│ └── ...
55+
├── main.tex
56+
└── metadata.yaml
57+
58+
- `main.tex` will be the main file that gathers the various chapters.
59+
See [below](#main-file) for the template.
60+
- `metadata.yaml` is a metadata file you’ll fill in as shown [below](#metadata-file).
61+
- `chapters/` contains the `.tex` files that make up your chapters.
62+
Give these files appropriate names.
63+
If necessary, you can further organize them into subfolders.
64+
See [below](#chapter-files) for the template.
65+
- `res/` and its subfolders are all optional and contain files associated with images you’ll include in your notes.
66+
In particular:
67+
- `drawio/` will contain Draw.io images in `.drawio.svg` format.
68+
- `ggb/` will contain GeoGebra projects (`.ggb` extension).
69+
- `py/` will contain Python scripts (`.py` extension).
70+
- `svg/` will contain SVG images, e.g. exported from GeoGebra.
71+
You can freely create other subfolders for different image types (e.g. PNG); just try to maintain good organization.
72+
73+
When compiling the PDF, a `build/` folder will be automatically generated, and if you’ve used SVG files, also an `svg-inkscape/` folder.
74+
The output PDF will be located at `build/main.pdf`.
75+
76+
#### Metadata file
77+
78+
Fill out `metadata.yaml` following this example:
79+
80+
```yaml
81+
course_code: "AB1CDE2"
82+
course_name: "Course name"
83+
teacher: "Surname, Name"
84+
start_academic_year: 2025
85+
program_level: "bachelor"
86+
program: "Name of Degree Program"
87+
language: "ita"
88+
formats:
89+
- "latex"
90+
authors:
91+
- "Surname, Name"
92+
- "Surname, Name"
93+
editors: []
94+
```
295
3-
> **English Version** | [Versione Italiana](#🇮🇹-versione-italiana)
96+
- `teacher` is the course teacher.
97+
- `program_level` is either `bachelor` or `master`.
98+
- `program` is the name of the degree program, in English.
99+
- `language` can be `ita` or `eng`.
100+
- `formats` is a list with elements among `latex`, `typst`, and `markdown`.
101+
- The names in `teacher`, `authors`, and `editors` must follow the `Surname, Name` format.
102+
- The `editors` field should initially be an empty list (`[]`). Later, if needed, it will be filled in like `authors`.
4103

5-
---
104+
#### Main file
6105

7-
## 🇺🇸 English Version
106+
This is the template for `main.tex`:
8107

9-
Thank you for considering contributing to the notes repository. To do so, follow the steps outlined below.
108+
``` latex
109+
% !TEX root = main.tex
10110
11-
### 🚀 Installation and Compilation
111+
\documentclass[italian]{HKNdocument}
12112
13-
#### Prerequisites
113+
% Add here your custom packages and commands
14114
15-
- **For LaTeX**: Complete TeX distribution (TeX Live, MiKTeX)
16-
- **For Typst**: [Typst](https://typst.app/) (version 0.12.0 or higher)
17-
- **For Python**: Python 3.x with dependencies from `requirements.txt`
115+
\title{}
116+
\shorttitle{}
117+
\author{}
118+
\docdate{First semester 2025/2026}
119+
\docversion{1.0}
18120
19-
#### Installation
121+
\begin{document}
20122
21-
1. Clone the repository:
22-
```bash
23-
git clone https://github.com/MuNuChapterHKN/Eta-Kappa-Notes.git
24-
cd Eta-Kappa-Notes
25-
```
123+
\include{chapters/first-chapter}
124+
\include{chapters/second-chapter}
26125
27-
2. Install Python dependencies:
28-
```bash
29-
pip install -r requirements.txt
126+
\end{document}
30127
```
31128

32-
#### Compilation
129+
- The comment `% !TEX root = main.tex` on the first line is not just a comment, but it indicates that this is the main file of the folder and the one that should be compiled.
33130

34-
**For LaTeX documents:**
35-
```bash
36-
cd latex/guide
37-
latexmk -pdf guide.tex
38-
```
131+
- Set the language (`italian` or `english`) as an option in `\documentclass`.
132+
133+
- Where indicated, you can import your own packages and define your commands.
134+
135+
- Fill in `\title`, `\shorttitle`, `\author`, and `\docdate`.
136+
- `\title` is the course name.
137+
- `\shorttitle` helps avoid title overflow into the page margin graphics.
138+
- `\docdate` indicates the semester and academic year.
139+
140+
- The actual content will be included using lines like `\include{chapters/first-chapter}` (replace `first-chapter` with your chapter's `.tex` filename, extension optional).
141+
142+
If some chapters are inside subfolders of `chapters/`, specify the correct path, for example `\include{chapters/subdirectory/first-chapter}`.
39143

40-
**For Typst documents:**
41-
```bash
42-
typst compile typst/guide.typ
144+
#### Chapter files
145+
146+
Chapter files begin with the following line:
147+
148+
``` latex
149+
\chapter[Short chapter title]{Full chapter title}
43150
```
44151

45-
### 🤝 Contributing Process
152+
The option in `[ ]` is only needed for chapters with long titles and can be omitted if unnecessary.
46153

47-
1. Fork the repository
48-
2. Clone **your** fork locally
49-
3. Create a new branch that briefly describes the changes you are making
50-
4. Push your changes to your fork
51-
5. Create a pull request to the main repository
154+
After that comes the actual content, divided into `\section`, etc.
52155

53-
Pull requests should be atomic and focused on a single change. If you have multiple changes, please create multiple pull requests.
156+
## 🔄 Repository workflow
54157

55-
For maintainers, please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and squash commits before merging.
158+
> [!NOTE]
159+
> This section is intended for maintainers.
56160

57-
---
161+
The repository workflow is designed to address the following goals:
162+
- The students who write notes should be able **not to care** about the repository if not for the commits, the maintainers should manage everything.
163+
- The students should work in a **clean branch**.
164+
- Updates to the released PDFs should **not be too frequent**.
58165

59-
## 🇮🇹 Versione Italiana
166+
### Branches
60167

61-
Grazie per aver considerato di contribuire al repository delle note. Per farlo, segui i passaggi descritti di seguito.
168+
- `main`: branch with all the notes, the index, and the compiled PDFs.
169+
- `structure`: just as the main, but without notes, index, and PDFs (only repository structure and templates)
170+
- `feat/*` and `fix/*` feature branches: created from `structure`, merge into `structure`
171+
- `notes/*` notes branches: created from `structure`, do not contain the notes of other courses
62172

63-
### 🚀 Installazione e Compilazione
173+
### Merges
64174

65-
#### Prerequisiti
175+
- feature branches $\to$ `structure`
176+
- `structure` $\to$ `main` (to update templates, etc.)
177+
- notes branches $\to$ `main` (to update the notes content)
178+
- `structure` $\to$ notes branches (preferably rarely, case \*)
66179

67-
- **Per LaTeX**: Distribuzione TeX completa (TeX Live, MiKTeX)
68-
- **Per Typst**: [Typst](https://typst.app/) (versione 0.12.0 o superiore)
69-
- **Per Python**: Python 3.x con le dipendenze in `requirements.txt`
180+
Some commits of `main` may be tagged and correspond to published versions.
70181

71-
#### Installazione
182+
Publication is not automated.
72183

73-
1. Clona il repository:
74-
```bash
75-
git clone https://github.com/MuNuChapterHKN/Eta-Kappa-Notes.git
76-
cd Eta-Kappa-Notes
77-
```
184+
### Roles
78185

79-
2. Installa le dipendenze Python:
80-
```bash
81-
pip install -r requirements.txt
82-
```
186+
#### Repository maintainers...
83187

84-
#### Compilazione
188+
- Develop in `structure`, possibly through feature branches
189+
- Manage all merges
190+
- Create the notes branches
85191

86-
**Per documenti LaTeX:**
87-
```bash
88-
cd latex/guide
89-
latexmk -pdf guide.tex
90-
```
192+
Naming convention: `notes/<course-name>-<teacher-surname>`, where the course name is in the appropriate language, lowercase, with words joined by hyphens and with numbers instead of I, II, etc.
91193

92-
**Per documenti Typst:**
93-
```bash
94-
typst compile typst/guide.typ
95-
```
194+
Examples: `notes/fisica-2-pirri`, `notes/fisica-dello-stato-solido-di-fabrizio`
195+
- Tell those writing notes to perform a `git pull` (case \*)
196+
197+
#### Notes writers...
96198

97-
### 🤝 Processo di Contribuzione
199+
- Only use their own notes branch
200+
- Perform a `git pull` when asked (case \*)
98201

99-
1. Fai un fork del repository
100-
2. Clona **il tuo** fork localmente
101-
3. Crea un nuovo branch che descriva brevemente le modifiche che stai apportando
102-
4. Invia le tue modifiche al tuo fork
103-
5. Crea una pull request al repository principale
202+
### Commits
104203

105-
Le pull request dovrebbero essere atomiche e focalizzate su una singola modifica. Se hai modifiche multiple, crea più pull request.
204+
Commits should be **atomic** and focused on single changes.
106205

107-
Per i maintainer, seguire la specifica [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) e fare squash dei commit prima del merge.
206+
For commit messages:
207+
- Please follow [**Conventional Commits 1.0.0**](https://www.conventionalcommits.org/en/v1.0.0/), but
208+
- omit the scope
209+
- introduce the commit type `notes:` for addition of notes content.
210+
- Consider following the **50/72 Rule**

0 commit comments

Comments
 (0)