diff --git a/README.md b/README.md index af916e1..1fb0e85 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,38 @@ # UoN Robot Wars project + ## What's this? This repository contains files generated by student efforts to begin building fighting robots at the University of Nottingham. + ## How can I gain write-access to it? -Please note that the automatic user-management tools have been deliberately disabled. Students involved in the project can -contact Steve Greedy to get login details. +Automatic user-management tools have been deliberately disabled. Students involved in the project can +contact Steve Greedy to get user accounts. Naturally, if you're reading this file on a local copy of the repo, you already have write permissions for your local copy! + ## What does it do? Git is a decentralised version control system. That is, it provides a mechanism for tracking file modifications, even when the -same file is edited by multiple users simultaneously. -## What do I do with it? +same file is edited by multiple users simultaneously, in different places, even without network access. + +## How do I use it? Anyone can create a local version of this repository on their own computer, provided they have git installed. Git is a standard component of most Linux distributions, but can also be found at git-scm.com for other OSes. Once you have a local repository based on this one, you can make changes to the files as you would with any other files. Once you're happy with the changes, you can then 'commit' them to the repository and (at your option, provided you have permission) push them to the -central repository so that the rest of the group can access them. If others have made changes, you can pull those from the +central repository, so that the rest of the group can access them. If others have made changes, you can pull those from the central repository to update your local copy. For more detail on how to actually use git, talk to Chris Stone or use your favourite search engine. ## Git? GitLab? GitHub? - * Git is an open-source revision control system that anyone can use on their own computer, independently of online services. -It does not, in general, have a web interface. - * GitHub is a commercially-operated web service that offers free publicly-visible git repositories to the general public, + * Git is an open-source revision control system that anyone can use on their own computer, with or without online services or remote repositories. +It does not, in general, have a web interface, or even a GUI (although GUIs are available). + * GitHub is a commercially-operated web service that offers free, publicly-visible git repositories to the general public, along with a web interface tio access them. * GitLab is a package that provides a web interface to git repos that can be run on private computers. Our central repo can -be accessed through a gitlab installation run privately in the UoN +be accessed through a gitlab installation run privately at the UoN. + +## Polite notes on usage +To keep everything tidy and accessible, all users should aim to: +1. Take care when naming files and directories. Characters that need escaping (such as spaces, and most punctuation) should be avaoided. Remember that Windows filenames are only partially case-sensitive. +2. Use our standardised part reference codes where appropriate, to avoid ambiguity. +3. Sort work into logically-named subdirectories/subfolders (except in the case of CAD data, where this causes difficulties) +4. Write meaningful commit messages. (See XKCD1296 for more detail) + -- libgit2 0.21.2