LGTM Devlog 8: Starting a git repo for an open source project from scratch
Tags: devjournal, github, git, opensource
Published: 2020-12-30 11:11:56

Next thing is to start a git repo. I've decided that LGTM will have a single repo for everything. This is less about going for a [monorepo](https://en.wikipedia.org/wiki/Monorepo), and more because I kind of like the idea that everyone who forks the LGTM repo to start a game is actually bringing with them an entire copy of the game. There's a chance I'll regret the decision later, but it can always be split.

There's nothing crazy in this repo at this stage, but I thought I'd share what the repo looks like, in case people were interested in seeing. You can browse the commit relevant to this post here: [8156f52](https://github.com/meseta/lgtm/tree/8156f523ad0321779e12e0385cdbcd7b9605748e), and I'll try to explain what's in it.

# Readme
The Readme is a very important file for open source projects. It describes what this repo is about, and the first file people will see when they visit your repo. It's in Markdown format so supports some formatting, and GitHub automatically displays the contents of this file named `README.md` on the repo's main page.

It lets people visiting your repo for the first time (might have landed there from a search result, or a bookmark they don't remember what for) quickly understand what your repo is about. It's a central place to link out to documentation, compiled binaries, and other resources a user might need to use your code/software. For now, mine just contains our splash image, and a link to the first blog post in this series.

# License
I've decided that I'm building LGTM fully in public. I'm going to be describing most of what I'm building on this blog anyway, so I thought I'd just share and open-source the code as well. In order to clarify under what conditions I'm sharing/open-sourcing the code, it's standard to have a `LICENSE.txt` containing the text of the license. GitHub actually detects what kind of license it is, and shows a little badge in the upper right giving viewers an idea of what it is.

I'm using the standard [MIT license](https://en.wikipedia.org/wiki/MIT_License), a very popular license for open source software. It means you're free to copy and edit my code (within these terms)!

# Contributing
Since this is an open source project, it is, in theory, open to contributions. However, as the maintainer of this project, I have a say in what contributions I accept, and how. The `CONTRIBUTING.md` file is there to explain to people how contributions can happen (possibly including a code of conduct for the community)

Unfortunately, as I would like to focus on developing LGTM in its early stages, I am not accepting public contributions for now; later on I would love to open it up to contributions. To communicate this clearly, I explain this in that file.

# Gitignore
A `.gitignore` is there to stop git from including files it shouldn't include.  I will have more `.gitignore` files within the nested folders of the repo, but the outer one here has a single entry for now called `.vscode`. This is because my editor will store some local project-specific data in this repo that would be either unusable by others because it contains a setup specific to my machine, or worse, conflict with someone else's setup. The `.gitignore` is there to avoid this kind of issue of machine-specific or files that shouldn't be shared, from being included in the repo.

# Gitattributes
A `.gitattributes` file is there to instruct git how to treat certain files or types of files. I have one entry in there that enables [LFS](https://git-lfs.github.com/) on the image in the assets folder. LFS is a way of storing large files without bloating the repo, since git cannot efficiently diff binary files like images, and will store a full copy of each revision of that file.

Our banner.png won't change much, but it does weigh in at 200kb, so if we end up with even a handful of copies of it (along with other images), the repo is going to get big really fast. So might as well set up LFS now.

One thing I haven't checked into the repo yet, is some additions to `.gitattributes` that force a certain line-ending behaviour (it avoids some weirdness when Windows and Linux users work on the same project because of some editors' tendency to change the line endings). This will come in in a future commit.

# Docs/Assets
Finally, I store the banner image in the repo itself. While git isn't great for big binary files like images, [LFS](https://git-lfs.github.com/) helps to some extent, but also it's still a good option to reference the image in the git repo itself to avoid having to rely on an external image host which may at some point decide to not host your images any more.

___

That's all that's in the repo for now! This is a fairly unremarkable initial repo for an open source project.