Commit 9029c0ddd98273f76006d46b413952da096a18b0
1 parent
9d8b60bf
Exists in
master
Minor changes to readme file, including a few guidelines for keeping the repo tidy.
Showing
1 changed file
with
21 additions
and
9 deletions
Show diff stats
README.md
| 1 | # UoN Robot Wars project | 1 | # UoN Robot Wars project |
| 2 | + | ||
| 2 | ## What's this? | 3 | ## What's this? |
| 3 | This repository contains files generated by student efforts to begin building fighting robots at the University of Nottingham. | 4 | This repository contains files generated by student efforts to begin building fighting robots at the University of Nottingham. |
| 5 | + | ||
| 4 | ## How can I gain write-access to it? | 6 | ## How can I gain write-access to it? |
| 5 | -Please note that the automatic user-management tools have been deliberately disabled. Students involved in the project can | ||
| 6 | -contact Steve Greedy to get login details. | 7 | +Automatic user-management tools have been deliberately disabled. Students involved in the project can |
| 8 | +contact Steve Greedy to get user accounts. | ||
| 7 | Naturally, if you're reading this file on a local copy of the repo, you already have write permissions for your local copy! | 9 | Naturally, if you're reading this file on a local copy of the repo, you already have write permissions for your local copy! |
| 10 | + | ||
| 8 | ## What does it do? | 11 | ## What does it do? |
| 9 | Git is a decentralised version control system. That is, it provides a mechanism for tracking file modifications, even when the | 12 | Git is a decentralised version control system. That is, it provides a mechanism for tracking file modifications, even when the |
| 10 | -same file is edited by multiple users simultaneously. | ||
| 11 | -## What do I do with it? | 13 | +same file is edited by multiple users simultaneously, in different places, even without network access. |
| 14 | + | ||
| 15 | +## How do I use it? | ||
| 12 | Anyone can create a local version of this repository on their own computer, provided they have git installed. Git is a | 16 | Anyone can create a local version of this repository on their own computer, provided they have git installed. Git is a |
| 13 | standard component of most Linux distributions, but can also be found at git-scm.com for other OSes. Once you have a local | 17 | standard component of most Linux distributions, but can also be found at git-scm.com for other OSes. Once you have a local |
| 14 | 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 | 18 | 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 |
| 15 | changes, you can then 'commit' them to the repository and (at your option, provided you have permission) push them to the | 19 | changes, you can then 'commit' them to the repository and (at your option, provided you have permission) push them to the |
| 16 | -central repository so that the rest of the group can access them. If others have made changes, you can pull those from the | 20 | +central repository, so that the rest of the group can access them. If others have made changes, you can pull those from the |
| 17 | central repository to update your local copy. | 21 | central repository to update your local copy. |
| 18 | 22 | ||
| 19 | For more detail on how to actually use git, talk to Chris Stone or use your favourite search engine. | 23 | For more detail on how to actually use git, talk to Chris Stone or use your favourite search engine. |
| 20 | ## Git? GitLab? GitHub? | 24 | ## Git? GitLab? GitHub? |
| 21 | - * Git is an open-source revision control system that anyone can use on their own computer, independently of online services. | ||
| 22 | -It does not, in general, have a web interface. | ||
| 23 | - * GitHub is a commercially-operated web service that offers free publicly-visible git repositories to the general public, | 25 | + * Git is an open-source revision control system that anyone can use on their own computer, with or without online services or remote repositories. |
| 26 | +It does not, in general, have a web interface, or even a GUI (although GUIs are available). | ||
| 27 | + * GitHub is a commercially-operated web service that offers free, publicly-visible git repositories to the general public, | ||
| 24 | along with a web interface tio access them. | 28 | along with a web interface tio access them. |
| 25 | * GitLab is a package that provides a web interface to git repos that can be run on private computers. Our central repo can | 29 | * GitLab is a package that provides a web interface to git repos that can be run on private computers. Our central repo can |
| 26 | -be accessed through a gitlab installation run privately in the UoN | 30 | +be accessed through a gitlab installation run privately at the UoN. |
| 31 | + | ||
| 32 | +## Polite notes on usage | ||
| 33 | +To keep everything tidy and accessible, all users should aim to: | ||
| 34 | +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. | ||
| 35 | +2. Use our standardised part reference codes where appropriate, to avoid ambiguity. | ||
| 36 | +3. Sort work into logically-named subdirectories/subfolders (except in the case of CAD data, where this causes difficulties) | ||
| 37 | +4. Write meaningful commit messages. (See XKCD1296 for more detail) | ||
| 38 | + |