dev-git-github-practice.qmd

# Creating your simulation model repository {#dev-git-github-practice}

This chapter puts into practice the workflow introduced earlier. You will now create a proper, version-controlled home for your simulation model. Your repository will serve as a **living record** of your project’s evolution — from conceptualisation and first prototype to final publication.

---

## Preparation

* [ ] Created a **GitHub account**.
* [ ] Created a **Zenodo account**.

In this session, we will be using the browser interface only. But do consider installing and configuring the rest of the software in order to be able to work locally in your own computer

---

## Join the course GitHub organisation

All course repositories are hosted under
👉 **[https://github.com/CoDArchLab-ABM](https://github.com/CoDArchLab-ABM)**

1. Accept the invitation sent by your instructor (check your GitHub notifications or email).
2. Once inside the organisation, you can see the list of other student projects.
3. You can also create repositories under your own GitHub username if you prefer, and later transfer them to the organisation.

> 💡 *Being part of the organisation helps with collaboration, visibility, and the use of shared templates.*

---

## Creating a new repository

You can create your repository **entirely through the GitHub web interface**, no local software required.

1. Go to your GitHub homepage → **Repositories → New**.
2. Choose owner as your user (you can later create a fork in the course organisation)
3. Name it following the convention:
   `project2025_<model-name>`
   (use only lowercase letters, digits, and underscores).
4. Initialise it with:

   * ✅ a **README.md** file
   * ✅ a **.gitignore** (choose the *R* template)
   * ✅ a **license** of your choice (e.g. MIT, GPL-3.0, CC-BY-4.0)
5. Set visibility to **Public**.

> 💡 *Starting with a README and license ensures that your project is immediately valid, citable, and shareable.*

If you **can work locally** (on your own computer or a managed laptop), you may also initialise the repository on your machine using Git, then push it to GitHub.

> NOTE: You can find a project template in the course organisation ([`project2025_template`](https://github.com/CoDArchLab-ABM/project2025_template)) with files and directories for the typical contents already created. You may "fork" the template for a model repository and modify it accordingly, or create it from scratch using the guidelines above and populate it with files as you develop your project.

---

## Populating your repository

Your repository should reflect a clean, modular project structure from the beginning.
Create the following files and folders — even if they remain empty for now.

```
project2025_<model-name>/
│
├── model/               # NetLogo models (.nlogo files)
├── data/                # Input data files (CSV, shapefiles, etc.)
├── results/             # Simulation outputs
├── analysis/            # R or Python scripts for analysis
├── docs/                # Markdown or PDF documentation
│   └── notes.md
├── LICENSE
├── README.md
└── .gitignore
```

If you work **in the browser**, use GitHub’s “Add file → Create new file” to add folders and files.
Each new file can be created and edited directly online.

When you edit a file:

1. Scroll down to “Commit changes.”
2. Write a short message describing your change (e.g. *Add empty folders and README*).
3. Choose “Commit directly to the main branch.”

This saves and versions your work immediately.

> 💡 *Even if you cannot install Git locally, you still gain the benefits of version control and public documentation.*

---

## Publishing version 0.1

Despite your repository might be empty, you may want to practice publishing your repositories in Zenodo or at least make sure that everything is ready for later publication.

Once your initial structure is in place:

1. **Set up GitHub–Zenodo connection**

   * Go to [https://zenodo.org](https://zenodo.org) → Sign in with GitHub.
   * Authorise Zenodo to access your repositories.
   * In Zenodo, enable archiving for your `project2025_<model-name>` repository.

2. **Create your first release**

   * In your repository → “Releases” → “Draft a new release”.
   * Tag: `v0.1`
   * Title: `Version 0.1 (initial structure)`
   * Description: a short note about what this version contains.
   * Click on the "Publish release" button.  

3. **Publish**

   * Once published, Zenodo will automatically mint a **DOI** for your repository snapshot.

4. **Update README**

   * Add the Zenodo **DOI badge** at the top of your `README.md`.
   * Example:

     ```markdown
     [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.xxxxxxx.svg)](https://doi.org/10.5281/zenodo.xxxxxxx)
     ```

> 💡 *This makes your project formally citable and demonstrates best practices for open science.*

---

## If you later gain local access

Once you can install and use Git locally, you can clone your repository and continue developing offline:

```bash
git clone https://github.com/CoDArchLab-ABM/project2025_<model-name>.git
```

Work as usual:

```bash
git add .
git commit -m "Implement new agent rules"
git push
```

Your history and Zenodo releases will remain intact — this is a seamless transition.

---

### Summary

| Step                     | Description                                               | Online only? |
| ------------------------ | --------------------------------------------------------- | ------------ |
| Create repository        | Initialise on GitHub with README, license, and .gitignore | ✅            |
| Add folders/files        | Use GitHub web editor                                     | ✅            |
| Commit and version       | Done via “Commit changes” in browser                      | ✅            |
| Publish release and DOI  | Connect to Zenodo                                         | ✅            |
| Clone locally (optional) | Use Git on your computer                                  | ❌            |

> 🧭 **Goal:** By the end of this chapter, your simulation project exists as a structured, public, versioned, and citable research artifact — even if you never installed Git.

## Writing your README file

Every GitHub repository starts with a `README.md` file.
It serves as the *front page* of your project and should answer three key questions:

1. **What is this project?**
2. **How can others use it or learn from it?**
3. **How can it be cited or extended?**

Below is a template you can copy into your repository’s README file and adapt to your project.
Sections marked with `<!-- comments -->` are suggestions to help you fill in the content.

---

### 📄 Example README.md Template

```markdown
# Project2025_<model-name>

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.xxxxxxx.svg)](https://doi.org/10.5281/zenodo.xxxxxxx)

## Overview

<!-- Briefly describe your simulation model in 2–3 sentences. -->
This project develops an agent-based model (ABM) that explores [process or phenomenon, e.g., settlement dynamics and trade interactions] in an archaeological context.  
It was created as part of the MA course *Agent-based Modelling for Archaeologists* at the University of [Your Institution].

## Concept and objectives

<!-- Describe what the model represents and what questions it addresses. -->
The model aims to simulate [describe processes, behaviours, or hypotheses].  
It is designed to help explore how [key mechanisms] influence [outcomes of interest].

## Model design

<!-- Summarise the main elements: environment, agents, and processes. -->
- **Agents:** [e.g., settlements, traders, households]  
- **Environment:** [e.g., spatial grid, network, landscape data]  
- **Key processes:** [list mechanisms such as migration, exchange, resource use]  
- **Temporal scale:** [e.g., yearly steps, 100 iterations]  

A full conceptual description is available in [`docs/notes.md`](docs/notes.md).

## Repository structure

\`\`\`

model/       → NetLogo model files (.nlogo)
data/        → Input datasets (CSV, shapefiles, etc.)
results/     → Simulation outputs
analysis/     → R scripts for analysis
docs/        → Documentation and notes

\`\`\`

## Usage

### Requirements
- [NetLogo](https://ccl.northwestern.edu/netlogo/)
- [R](https://www.r-project.org/) (optional, for analysis)

### How to run
1. Open `model/<your_model>.nlogo` in NetLogo.  
2. Use the Interface tab to initialise and run the simulation.  
3. Use **BehaviorSpace** (NetLogo menu → Tools → BehaviorSpace) to run batch experiments.  
4. Store output files in the `results/` folder for later analysis.

## Results

<!-- Mention what kind of outputs or figures you expect. -->
Simulation results include [key indicators, e.g., settlement sizes, trade volumes, population changes].  
Analysis scripts in `scripts/` generate plots and summaries.

## License

This project is licensed under the [LICENSE](LICENSE) file included in the repository.

## Citation

If you use or adapt this model, please cite:

> [Your Name]. (2025). *Project2025_<model-name>: An agent-based model of [topic]*. Version 0.1. DOI: [https://doi.org/10.5281/zenodo.xxxxxxx](https://doi.org/10.5281/zenodo.xxxxxxx)

## Acknowledgements

This work was developed as part of the MA course *Agent-based Modelling for Archaeologists: From Concept to Application and Publication*,  
taught by Andreas Angourakis at the University of Cologne.

```