Repository navigation
Contributing to GMU ASRC code
Git is mainly built for code, but you can put any file type inside. However, Git has some limitations that make storing certain things impractical.
Github in particular has limits on the size of files you can add to a repository. In general, you should not store files larger than 50 MB in a git repository. However, in some cases, you can use Git LFS to store large files that need to be version controlled.
Git stores a history of every file and every change that was ever made in the repository. This means that once you put something in a repo, it can be accesssed by anyone by looking at the Git history!
This means you should NEVER store a secret in Git.
Aside from secrets, you should also be mindful of repository bloat. Not every file needs to be version controlled. For example, you should not store Python Cache files that get automatically generated when you run a script. You should avoid storing:
- distribution binaries
- OS-specific hidden files like desktop.ini, .DS_Store, thumbs.db, etc.
- entire static websites
- log files and experimental results
Once they're there, they cause the repository to be slower to work with, and they are very difficult to remove. You'd essentially have to tell each person working on the project to also get rid of those files manually.
A .gitignore file tells Git to ignore certain types of files or folders. This means the file won't be version controlled, its history won't be tracked, it won't appear on the Github remote server, and it won't get downloaded to other collaborators when they clone or pull from the remote. People often make template .gitignore files for the most common file types and patterns that Git should ignore.
Git has several requirements for branch names. [citation needed]
Branch names should reflect the feature being added. They should also be short (you may need to type them over and over again), and usually contain no uppercase letters.
Each branch that isn't main should be for a single feature or experiment. If your pull or merge request has multiple features or changes, and one of them is broken, then we can't merge either feature because they're in the same branch. See: Git Flow workflow [citation needed, also state alternatives]
In shared repositories, try not to push to other people's branches without them knowing.
Write good commit messages! A good commit message should:
- Have less than 77 characters on each line
- Summarize the contents or changes in a commit in the first line
- Be useful to both the future you and your collaborators
A good commit message can also help you write a changelog later.
Comments are not just for other people. They're invaluable when you stop working on a project for a month, come back, and need to quickly orient yourself with your past code. Get in the habit of writing good comments!
Avoid re-explaining your project by documenting it. Good documentation isn't easy, and you probably won't have perfect documentation on the first try. But you can't predict every question people will have, and you can't start improving your documentation unless you have a draft to share. So start documenting early and start getting feedback early, and maybe you'll be a little bit closer to the dream of never repeating yourself.
Please consider the privacy of your lab-mates. Some project wikis are public on the internet. Do not post pictures of them without their permission. Do not share email addresses here (instead link to their page if they're a professor, or direct readers to the Slack which is access controlled and has work email addresses of everyone).
Additionally, some projects may be confidential, under NDA, or otherwise secret. Be aware of this when sharing details of projects, especially when posting pictures here. Sometimes pictures need to go through a pub-release or review process.
Always remember: The internet never forgets.