GitHub Repository Management
Module 1 - GIST 604B
Building Professional Portfolios Through Proper Repository Structure
Today we're covering professional GitHub repository management. This is about building your portfolio
and showing professionalism through proper repository structure and documentation.
Why Repository Management Matters
💼 Your GitHub is Your Portfolio 🏢 Real-World Statement ⏰ Time Saver 🙏 Future-You Will Thank You
Repository management = Professional communication
Your GitHub profile is your public portfolio. Repositories are often the first impression for employers.
I've heard countless tech managers say "I've hired people based on their GitHub." Good organization shows
professionalism and attention to detail.
Essential Repository Components
project-name/
├── README.md ← Your repo's front door
├── LICENSE ← Legal foundation
├── .gitignore ← Keep it clean
├── data/ ← Sample data
├── src/ ← Source code
├── docs/ ← Documentation
├── tests/ ← Test files
└── examples/ ← Usage examples
README, LICENSE, .gitignore + organized directories = Professional repository
Every professional repository needs essential components: README for documentation, LICENSE for legal clarity,
.gitignore to keep things clean, and proper directory structure to organize your work. We'll dive into each of these.
README.md - Your Repository's Front Door
Must Include:
✅ Project title and brief description
✅ What problem it solves
✅ How to install/use it
✅ Basic examples
✅ How to contribute (for public projects)
✅ Contact information
🔗 Live Examples: Leaflet |
GDAL |
GeoPandas
README.md is the first thing people see. It's displayed on your repository homepage. A good README should
answer: what is this, why does it exist, how do I use it? Let me show you some excellent examples from
major GIS projects.
README Examples: Good vs Bad
❌ Bad Example:
# Project 2
My code for class
`python main.py`
Too vague, no context, no explanation
✅ Good Example:
# Earthquake Mapper
Interactive Leaflet map visualizing
USGS earthquake data from the past
30 days.
## Features
- Real-time data from USGS API
- Circle markers sized by magnitude
- Popup info for each earthquake
## Installation
```bash
pip install -r requirements.txt
python app.py
```
## Usage
Visit http://localhost:5000
Look at the difference. The bad example tells you nothing. The good example immediately tells you what it
does, why it's useful, how to install it, and how to use it. Which repository would you want to work with?
LICENSE - Legal Foundation
⚠️ Without a license = All Rights Reserved
Nobody can legally use, modify, or distribute (even if public!)
Common Choices:
MIT - Permissive, minimal restrictions, maximum adoptionGPL v3 - Copyleft, modifications must remain openApache 2.0 - Patent protection, enterprise-friendly
🔗 Add via GitHub: choosealicense.com
Without a license, your code is "All Rights Reserved" by default—nobody can legally use it! Always add a license.
MIT is great for maximum adoption, GPL ensures derivatives stay open, Apache 2.0 adds patent protection.
We'll demo adding a license via GitHub's interface.
.gitignore - Keep Repositories Clean
What to Ignore:
Operating System Files:
.DS_Store
Thumbs.db
desktop.ini
IDE Configurations:
.vscode/
.idea/
*.swp
Dependencies:
node_modules/
venv/
__pycache__/
Secrets & Configs:
.env
config.local.json
*.key
🔗 Templates: github.com/github/gitignore
.gitignore tells Git which files to ignore. You don't want OS files, IDE configs, dependencies, or secrets
in your repository. GitHub provides templates for every language. We'll use the Python template for our projects.
Professional Directory Structure
spatial-analysis-toolkit/
├── README.md ← Project overview
├── LICENSE ← Legal terms
├── .gitignore ← Ignore patterns
├── requirements.txt ← Python dependencies
├── src/ ← Source code
│ ├── __init__.py
│ ├── spatial_utils.py
│ └── visualization.py
├── data/ ← Sample data
│ ├── README.md ← Data documentation
│ └── sample_points.geojson
├── docs/ ← Documentation
│ ├── installation.md
│ └── usage.md
├── tests/ ← Unit tests
│ └── test_spatial_utils.py
└── examples/ ← Usage examples
└── basic_analysis.ipynb
Consistency helps everyone (including future-you)
Organize your repository logically. Source code in src/, data in data/, docs in docs/, tests in tests/,
examples in examples/. This structure is immediately recognizable to other developers.
Markdown Basics for Documentation
Markdown:
# Heading 1
## Heading 2
### Heading 3
**bold** and *italic*
- List item 1
- List item 2
1. Numbered item
2. Another item
[Link text](url)
```python
code block
```
Renders as:
Heading 1
Heading 2
Heading 3
bold and italic
Numbered item Another item Link text
code block
🔗 Reference: markdownguide.org
Markdown is simple formatting for documentation. Headers with #, bold with **, italic with *, lists with - or 1.,
code blocks with triple backticks. Let's do a live demo creating a README in GitHub.
Writing Effective Documentation
✅ Write for beginners ✅ Explain "why" not just "what" ✅ Include prerequisites ✅ Show expected output ✅ Troubleshooting section ⚠️ Keep it updated!
Write for someone who knows nothing about your project. Explain why decisions were made. Include prerequisites
and troubleshooting. Most importantly, keep documentation updated—outdated docs create more problems than they solve.
Professional Repository Naming
✅ Good Names:
spatial-analysis-toolkitleaflet-earthquake-mappostgis-performance-benchmarksqgis-plugin-template
❌ Bad Names:
project2 - Too genericMy GIS Tool - Spaces cause issuesFINAL_PROJECT_REALLY_FINAL - Unprofessionalasdf - Not descriptive
Use lowercase with hyphens: descriptive and specific
Repository names should be lowercase with hyphens, descriptive, and specific. "leaflet-earthquake-map" tells
you exactly what it is. "project2" tells you nothing. Consistent naming shows professionalism.
Writing Clear Commit Messages
✅ Good Commit Messages:
Add elevation data processing function
Update README installation steps
Fix coordinate precision bug in distance calculation
Refactor spatial query logic for performance
❌ Bad Commit Messages:
fixed stuff
wip
asdf
updated files
more changes
💡 Best Practices:
Present tense: "Add feature" not "Added feature"
Reference issues: "Fix #42" or "Closes #15"
Be specific and descriptive
Clear commit messages tell a story of your project's development. Use present tense, be specific, reference
issues when relevant. "Add elevation processing function" is much better than "fixed stuff."
Branching Strategy
main branch (stable, working code)
│
├──── feature/add-postgis-support (new functionality)
│
├──── fix/coordinate-precision (bug fixes)
│
└──── docs/update-installation (documentation updates)
main = stable, production-ready codefeature/ = new functionality developmentfix/ = bug fixesdocs/ = documentation updates
We'll dive deep into branching in Video 4
Keep your main branch stable. Do development work in feature branches. Clear branch naming conventions make
collaboration easier. We'll cover this in much more detail in the next video on collaborative workflows.
Repository Settings & Configuration
🔓 Public vs 🔒 Private: 📝 Description & Topics: 📄 GitHub Pages: 🐛 Issue Templates: 🤖 GitHub Actions:
🔗 Demo: We'll explore these settings live
Repository settings matter for discoverability and professionalism. Add description and topics so people can
find your work. Consider GitHub Pages for documentation. We'll demo these settings in GitHub.
GitHub as Your GIS Portfolio
📌 Pin Important Repositories 👤 Complete Profile 📊 Contribution Graph 🏢 Organizations 📝 Profile README username/username repo for profile page
🔗 Examples: giswqs |
awesome-profile
Your GitHub profile IS your portfolio. Pin your best repositories, complete your profile, keep active with a
consistent contribution graph. Create a profile README by making a repository with your username. Let me show
you some great examples.
Assignment: M1A3
Create a Professional GIS Repository
✅ Proper structure (README, LICENSE, .gitignore, directories)
✅ Professional README with all essential components
✅ Appropriate license and .gitignore
✅ Simple Python GIS script (spatial "Hello World")
✅ Clean commit history with good messages
✅ Link from GitHub Classroom assignment
🤖 Automated Validation:
M1A3 is your chance to practice everything we've covered. Create a professional repository with proper structure
and documentation. GitHub Actions will validate your work. Think of this as a template for all future projects.
Essential Resources
📚 Bookmark these—you'll use them throughout your career
Here are essential resources. GitHub Docs for platform features. Markdown Guide for formatting. Choose a License
for license selection. Gitignore templates for every language. And examples of excellent READMEs from major GIS projects.
Key Takeaways
✅ Repository management = professional communication
✅ Four essential files: README, LICENSE, .gitignore, structure
✅ Documentation is for others AND future-you
✅ Small details create professional impression
✅ Your GitHub IS your portfolio
Practice good habits now = portfolio-ready later
Ready for M1A3? Let's build professional repositories!
To wrap up: Repository management is about professional communication. The four essential files are non-negotiable.
Documentation helps others and future-you. Small details matter. Your GitHub is your portfolio. Practice these
habits now, and they'll serve you throughout your career. Ready for M1A3!