Commit 86b3b1a9 authored by Cassandra Gould van Praag's avatar Cassandra Gould van Praag
Browse files

add gitlab tutorials

parent 3134c5f8
Pipeline #10477 passed with stages
in 2 minutes and 22 seconds
......@@ -40,10 +40,10 @@ Coming soon
## For WIN members
### Benefits
#### Version control ![version-control](../../img/icon-version-control.png)
WIN members will be encouraged to develop their analysis pipelines into standalone scripts and store these on the [WIN GitLab instance](https://git.fmrib.ox.ac.uk). We will support our members in using git to version control their code, and employ best practice in ensuring their pipelines are robust and accurate.
WIN members will be encouraged to develop their analysis pipelines into standalone scripts and store these on the [WIN GitLab instance](https://git.fmrib.ox.ac.uk). We will support our members in using git to version control their code, and employ best practice in ensuring their pipelines are robust and accurate. Find out more about [using GitLab](gitlab.md)
#### Citable research output ![doi](../../img/icon-doi.png)
Versions of analysis code can be assigned a digital object identified (DOI) using [Zenodo](https://zenodo.org) by uploading them from GitLab. Once a DOI has been created, your analysis code becomes a citable object which you can add to your list of research outputs.
Versions of analysis code can be assigned a digital object identified (DOI) using [Zenodo](https://zenodo.org) by uploading them from GitLab. Once a DOI has been created, your analysis code becomes a citable object which you can add to your list of research outputs. Find out how to [create a doi for your repository](gitlab/4-2-you-doi.md).
#### Reproducible methods detail ![reproduce](../../img/icon-reproduce.png)
Alongside your analysis code, WIN members will be supported in implementing a "[wrapper](https://techterms.com/definition/wrapper)" script which can:
......@@ -68,7 +68,7 @@ Detailed guidance on how to use the Open Analysis wrapper will be produced durin
You are free to include whatever material you wish in your repository. We have created this [guide on what to include](analysis/repo-include.md) to list some of the pages and sections which may be beneficial for readers. See also our guide on [how to license](repo-license.md) your material.
#### Creating a doi
We recommend using zenodo to create a doi for your material. See see the [creating a doi](analysis/doi.md) page for instructions.
We recommend using zenodo to create a doi for your material. See see the [creating a doi](gitlab/4-2-you-doi.md) page for instructions.
## Working group members (alphabetically)
We are grateful to the following WIN members for their contributions to developing the Open Analysis tools
......
......@@ -34,7 +34,7 @@ Take a look at the Open WIN "[Data Sharing Decision Tree](https://git.fmrib.ox.a
4. **What do we need?**: Describe what contributions you would like to receive. Link to your CONTRIBUTING.md file for more information.
5. **Who are we?**: Identify who you are. Link to your lab pages.
6. **Contact us**: Give clear instructions for how people can get in touch.
7. **Acknowledgements and citation**: Give clear guidance on how people should cite your material. This should include the [doi for the repository](doi.md) and any supporting papers.
7. **Acknowledgements and citation**: Give clear guidance on how people should cite your material. This should include the [doi for the repository](gitlab/4-2-you-doi.md) and any supporting papers.
### CONTRIBUTING.md
......
---
layout: default
title: Git and GitLab
parent: Open WIN Tools
has_children: true
nav_order: 5
---
# GitLab
{: .fs-9 }
How to use the WIN GitLab instance for your code and documentation
{: .fs-6 .fw-300 }
---
![open-tasks](../../img/logo-gitlab.png)
## Overview
GIT is a service which allows version control of material and syncing between local (on your computer) and remote (on a server, accessible through a web browser) versions of material. These remote and local versions are useful for backup and collaboration, where different users can access the same remote content.
WIN provide a git service using the open source [GitLab software](https://about.gitlab.com). We have installed GitLab on our internal servers, so you can use it to maintain your material in a space where we have complete control over who can access it.
GitLab is best used for the management of text-based documents with some pictures (not nifti brain images!). This mainly covers code and documentation. It is also useful for project management by logging issues and milestones, and tracking collaboration.
### Benefits
#### Version control ![version-control](../../img/icon-version-control.png)
GitLab manages your version control. This means that each change you make to the remote repository is tracked and can be reversed. This is helpful for undoing changes (you can revert to earlier points in time) and tracking who has made changes on a collaborative project.
#### Citable research output ![doi](../../img/icon-doi.png)
Your gitlab repository can be assigned a digital object identifier (doi). This means everything containing within your repository can be cited as a research output, be it code or documentation. Find out how to [create a doi for your repository](gitlab/4-2-you-doi.md).
#### Managed and attributable collaboration
Git and GitLab are an excellent resource for inviting others to contribute to your material. Potential collaborators can be internal to WIN or external. Changes can be incorporated automatically if the collaborator is trusted and known to you (invited directly), or suggested via a "merge request" if the collaborator is not part of your invited group. This process also makes it very easy to follow who has made what contribution, so they can be appropriately attributed for their efforts.
#### GitLab pages
GitLab pages allows you to build professional looking websites, like this one! It is relatively straightforward to build a simple website to share your work with the world, and the options for building in additional complexity are endless.
## How to use
See the [tutorials for gitlab]() section for guides on using git and GitLab at WIN.
### Who should I ask for further advice about using GitLab
The Open WIN community are a great resource for support in using GitLab. [Join the community](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/contact/) and try asking your question on slack!
You are very welcome to as the [Open WIN Engagement Coordinator](https://open.win.ox.ac.uk/pages/open-science/community/Open-WIN-Community/docs/community/community-who/#community-coordinator---cassandra-gould-van-praag-sheher) for specific advice on using GitLab.
Technical issues on the GitLab instance should be directed to [WIN IT](https://sharepoint.nexus.ox.ac.uk/sites/NDCN/FMRIB/IT/Pages/default.aspx).
---
layout: default
title: 1.1 Using the command line
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 1
---
# Using the command line
{: .fs-8 }
How to work with your computer via the command line
{: .fs-6 .fw-300 }
---
The most direct way to interact with a computer is via the “command line”. This is a simple text interface, but it can be used to powerful effect as there is no overhead of system resources (or programming work!) in generating a graphical user interface (GUI). You can also work quickly by keeping your fingers on the keyboard and avoiding reaching for the mouse! 🐭
Using the command line requires you to pay close attention to spacing and case (upper or lower) of text commands, as these modify the effect of the commands you type. There is no spell check in command line! If you type something wrong, insert or remove a space where there shouldn't be, or put an uppercase letter where there should be a lower case one, the command won't work. This can make the command line feel pretty unforgiving, but you'll get used to it 😊. Most commands will have associated “help” files and there is always lots of examples and documentation on the internet.
We will be using the command line to install some programs, and communicate with our online repository which holds our documentation.
## How to access your command online
We will be using a unix based command line, as this is consistently available across unix/linux systems (for example high performance computing clusters), Mac OS and Windows OS.
### Mac users
On a Mac the program to access your command line is called "Terminal". Access your terminal via the applications launcher, or press command (⌘) and space and start typing "terminal".
### Windows users
From Windows 10 onwards you can access a unix command line using the application "Powershell". Search for Powershell in the applications directory from the start button.
## Basic command line tutorial
Launch your command line application and have a go at completing [Unix Tutorial 1 from the University of Surrey](http://www.ee.surrey.ac.uk/Teaching/Unix/unix1.html). [Tutorial 2 (up to rmdir)](http://www.ee.surrey.ac.uk/Teaching/Unix/unix2.html) will also be helpful for what we're aiming to achieve.
After you have completed these tutorials, you should be able to do this via command line:
1. Navigate to a directory;
2. List the contents of that directory;
3. Make a new folder called “test”;
4. Go into the “test” folder and print the full path of that folder;
5. Delete the “test” folder.
This will be 90% of what you need to use GitLab!
---
layout: default
title: 1.2 Writing in markdown
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 2
---
# Writing in markdown
{: .fs-8 }
How to write documents using Markdown syntax
{: .fs-6 .fw-300 }
---
Markdown is a simple syntax for formatting text and adding graphics to documentation. Writing documentation using syntax (rather than Microsoft Word, for example), makes it easy for different programs to interpret what you have written and display it according to fixed rules. A markdown document can be easily transferred to a Word document, a pdf, and back again. By contrast, have you ever tried to copy-past from a pdf into Word?! Some characters just don't translate...
Using markdown also supports you to use "heading" identifiers, rather than simply changing the font size. This is because it is so *easy* to use heading syntax and it is comparatively complex to change a font size! This makes for content which is more accessible to screen readers used by individuals with a visual impairment ✌🏻 ✌🏼 ✌🏽 ✌🏾 ✌🏿
Markdown is used by GitHub to translate your text and formatting into webpage (GitHub Pages) content. You will be writing your documentation (maybe in [Atom](1-3-atom.md)) using markdown syntax, and it will automatically be rendered into something beautiful on your Pages site.
There are *many* markdown tutorials online which you can follow. I've listed the syntax I use most commonly below:
```
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
![image alt text](image path)
*italic*
**bold**
***italic bold**
```
P.S. There is no shame in having a markdown cheat-sheet pinned to your virtual or physical wall 😉
---
layout: default
title: 1.3 Atom text editor
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 3
---
# Atom text editor
{: .fs-8 }
How to set up and use Atom for writing markdown
{: .fs-6 .fw-300 }
---
![logo-atom](../../img/atom-200.png)
Atom is my fave editor for all types of "code". Python, bash, markdown, html... I've not tried with LaTeX, but I wouldn't be surprised if it can handle that. My guess is it probably can't handle MATLAB, but that's cool.
## Why I love Atom
What I particularly love about Atom is that I can switch between different languages very comfortably), and Atom takes care of everything the same way, no matter what you are writing. It handles the colours, the spacing, the formatting, [linting](https://en.wikipedia.org/wiki/Lint_(software)), the keyboard shortcuts, autocompletions, commenting, spell checking, searching / find+replace across multiple files, all the important stuff! I guess that is what you get from an open source tool developed by and for users who write code for a living! Other tools are available which I'm sure do a great job, but this is the one I am most comfortable with and consistently pleased by.
## Why you should use Atom
To host your documentation on GitHub pages, you're going to be writing across multiple documents, and potentially in more than one language. Atom also has a directory tree on the left which enables you to navigate around your project file easily, and also do things like create, duplicate and delete files using good old point-and-click.
Atom also provides a graphical point-and-click way of committing changes to your GitHub repo. This can be useful if you're not familiar with the process, but for these tutorials we're going to stick to command line and the terminal for GitHub, because you get more informative error reports.
## How to start with Atom
Before we crack on with creating and editing documentation, I'd love for you to get familiar with working in Atom. Here's a short video which shows you how to [install and start using Atom](https://www.youtube.com/watch?v=EyG20hhON6E).
There are tones of packages you can add on to make your workflow easier, but for these tutorials you'll only need the markdown basics which come preloaded.
Thanks, Atom. We love ya.
---
layout: default
title: 2.1 Your GitLab account
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 4
---
# Access and connect to your GitLab account
{: .fs-8 }
Access your GitLab account
{: .fs-6 .fw-300 }
---
Access GitLab by visiting [https://git.fmrib.ox.ac.uk](https://git.fmrib.ox.ac.uk) in a web browser and log in (using the LDAP tab) with your WIN IT username and password.
The git server identifies and authenticates you (or rather your computer) using an [SSH key pair](https://www.ssh.com/academy/ssh/public-key-authentication). This means we need to create a key pair to authenticate the connection from your local computer to the remote repository.
From your terminal, follow the instructions here [to create an SSH key pair for your local computer](https://sharepoint.nexus.ox.ac.uk/sites/NDCN/FMRIB/IT/User%20Guides/SSH.aspx#title11)
You will be asked to provide a file name for the key. Leave this blank to accept the default location of ~.ssh/id_rsa.
You will be asked to create a password. This password will be used by the git system to read the contents of your ssh key file (i.e. confirm your identity) when you send information to your repository. Do not use the same password as your WIN IT account password.
Once you have created the key, enter `cd ~` in your terminal, then `cat .ssh/id_rsa.pub` to read the contents of the SSH key file into the terminal. Copy and paste the contents into the SSH keys section of your profile settings on git.fmrib.ox.ac.uk (accessed via User Settings > SSH Keys - the "key" icon on left menu bar.
---
layout: default
title: 2.2 Global git configuration
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 5
---
# Global git configuration
{: .fs-8 }
Configure git on your system (one time only)
{: .fs-6 .fw-300 }
---
You need to set a few variables so git knows who you are and who is making changes to your material. This is done once only for each user on the computer.
The easiest way to set up your configuration is to make a repository. This generates a series of instructions to follow which are unique to your account.
Create a new project in the GitLab web interface called “test-git-project” (keep it private and do not initialise a readme). The next page will then provide the instructions for configuring git on your computer for the first time.
Enter the “Git Global setup” commands into your terminal, one line at a time. Note if you are a Mac user, you may want to additionally configure git to [ignore the .DS_store files](https://www.jeffgeerling.com/blogs/jeff-geerling/stop-letting-dsstore-slow-you) which are created every time you browse a directory in finder.
You can then list the contents of your git config file using the command below, and check the above variables have been stored.
```
git config --list
``
---
layout: default
title: 2.3 Your local repository
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 6
---
# Create a local version of your repository
{: .fs-8 }
Create a local copy of your first online repository
{: .fs-6 .fw-300 }
---
Currently your "test-git-project" exists online and your computer is configured to access it. We now need to create a local version so you can make changes on your computer and sync them up with the remote (online) version.
In your terminal, move to the directory where you would like your local version of the repository to be stored. Enter the "Create a new repository" commands into your terminal, one line at a time.
Note you will be asked for the SSH key password you generated when you [first accessed your gitlab account](2-1-starting-gitlab-account.md).
Below is a brief explanation of what each line is doing. You'll learn more about some of these commands in the [git basics tutorial](2-4-starting-git-basics.md).
After entering these commands, return to the [gitlab webpage](https://git.fmrib.ox.ac.uk) and refresh your project. You will now see that the instructions for creating a new project have gone and the commit message you just entered is shown on the top.
`git clone git@git.fmrib.ox.ac.uk:<your-account-name>/test-git-project.git`
The git clone command creates a copy of the repository (a “clone”) hosted at the address provided, and places it on your local machine in the directory you are currently in. This creates another directory (here called “test-git-project”) which includes all the tracking information required to log the versioning of the contents of this directory.
`cd test-git-project`
This navigates into the newly created directory. Now you are in the new repository folder you can use `ls –la` to view all the files in that directory. You will see that a file `.git` has been created. This relates to the tracking information created in the above step.
`touch README.md`
Touch is a unix command to create an empty file (here called “README.md”). If the file already exists, the touch command updates the files timestamp.
`git add README.md`
The `git add` command adds the file `README.md` to a ‘staging’ area. This is an index of files which will be added or amended in the remote repository. You can check to see what is in the staging area by entering the command `git status`. If you run `git status` after the git add command, you will see that `README.md` is listed as a new file but has not yet been ‘committed’ to the repository.
`git commit -m "add README"`
The `git commit` command records changes to the repository. This stores the current contents of the index (created with add above) in a new commit, with the `–m` flag to instruct the commit to be described with a message. The message is our description of what has been changed in the repository since our last commit. This message should be concise (<72 characters is suggested so it can be read on a single line) and descriptive. More complete descriptions of the commit changes can be added in the form of a full message or log (see this [guide on best practice for commit messages](https://medium.com/@steveamaza/how-to-write-a-proper-git-commit-message-e028865e5791)). The indexed files are still currently in the staging area and not your at your remote repository.
`git push -u origin master`
The `git push` command updates the remote references (those held on the gitlab server) with the local references (those you just created with the git commit command). The `–u` flag adds “upstream” tracking references. `Origin` is a nickname for the remote server and `main` is the name of the “master branch” of your repository, with a branch being the line of development you are working on.
---
layout: default
title: 2.4 Basic git commands
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 7
---
# Basic git commands
{: .fs-8 }
Use these commands to do 90% of your work
{: .fs-6 .fw-300 }
---
## I am NOT a git wizard
Practicing some radical transparency here, folks 😉. I can do enough git to get buy, and just about fix things when they break. Every time I break something, I learn a little more, and that works for me 😊. Seems I'm not alone.
![xkcd-git](https://imgs.xkcd.com/comics/git.png)
While I think it is SUPER cool to know everything about git and understand all the stuff, I totally respect that not everyone has that much time available to learn all the new things, and to expect everyone to be a wizard at something before they can participate makes for a very exclusive and unwelcoming community.
In the spirit of inclusivity, I'm going to show you the git commands I know, and then you too will be able to do just enough git to get by, and make use of this excellent resource in a way which works for you.
## Watch and learn
We're not yet going to actually practice doing these things right now. I'd just like you to become familiar with (memorize?!) them. You'll get a chance to use them when you have a go at [contributing to this repository](3-3-play-with-this-page.md), and again when you [make your pages site](4-2-Make-your-Pages-site.md).
## The three(ish) stages of adding to your repository online
For reasons which are better explained by someone who understands how git works more completely than I do, there are three stages (commands) required to transfer your local changes to your online repository for others to see.
**All of this happens in your command line application**. To use the commands, you'll be sat in the directory which contains your code which is being tracked by git, and entering the commands from there.
While entering all these commands, keep an eye on the messages appearing in your command line application. They may look incomprehensible at first, but with a little practice and patience you be able to identify the key parts and work out what is happening or going wrong!
### 0. Ask git to tell you what has changed
I love `git status`. Sometimes I know exactly what I've changed, and sometimes I'll have been jumping all over the place changing multiple files. Before I upload any changes, I'll usually run the `git status` command to remind me of what files I've been working on, so I can write a sensible commit message (see below).
### 1. Add
`git add your-file-name`
Tell git to "add" the file which you have changed (here called *your-file-name*)" to a staging area, ready to be updated. You can add individual files buy repeating the line with each file name, or you can use `git add .` to add everything which has been changed. I use this a lot.
### 2. Commit
Once you've added files to the staging area, you are ready to "commit" these to your repository. When we do this, we'll add a message for yourselves and our contributors explaining what changes we made in those files. The `-m` "flag" in the command below denotes that what follows will be your commit message.
`git commit -m "fixed broken link"`
Here I'm saying that the change I made in the file added above was to fix a broken link.
Your commit message can be anything you like, but there are some [best practice guides you can follow](https://chris.beams.io/posts/git-commit/) if you want to get deep. I like to keep it short and meaningful. In essence, you should be able to look back at your commit log and get an idea of the important things you did at each stage, incase you need to come back to a specific point later.
### 3. Push
You've added files to your staging area, you are committed to uploading them, now you actually need to **push** them to your repository. This one is easy.
`git push`
Everything you have added will be uploaded ("pushed") to your repository.
At this point (especially if it is a big load of changes I'm uploading) I'll often skip excitedly over to my online repository and have a look at my commit and the file changes. It's almost as if I don't trust the magic!?! 😉
![gif-basic-git](../../img/gifs/basic-git.gif)
Give it a few minutes to let the changes take effect, then go back and refresh your Pages site. Boom! Updated content.
![gif-basic-git-show-changes](../../img/gifs/basic-git-show-change.gif)
---
layout: default
title: 3.1 Collaborating on GitLab
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 8
---
# Are you a stranger or a known collaborator?
{: .fs-8 }
Two ways to contribute to a GitLab repository, depending on whether you are already known to and trusted by the repository owner
{: .fs-6 .fw-300 }
---
## Assuming you are a "stranger" to the repository owner
In my experience, a contribution to a repository doesn't come out of nowhere. Often you will have been having a bit of a chat in someone's repository issues (more on that later), and they will say, "Hey, that's a great idea! Do you want to submit a merge request?!". This is your invitation to contribute!
By "stranger" I mean that you are not one of the people who have access to make changes to the repository without going through a gate keeper. Your gate keeper is the process of the pull request which is review by the repository owner.
## If you know the repository owner
You can also submit changes in a more straight forward way if you have ben added as a collaborator to a repository. This requires the repository owner to have agreed this with you in advance, which we're not going to assume has happened here. You can follow a detailed presentation on [how to add collaborators to your repository here](https://docs.google.com/presentation/d/1VasZl8YsYMfhi1zYaYZ-kWykjp4T-ZqE5YrOImsC_Kg/edit#slide=id.g1568089626_6_46)
Coming soon
{: .label .label-yellow }
**This documentation needs to be updated for GitLab**
---
layout: default
title: 3.2 Collaborating with a stranger
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 9
---
# Collaborating with a stranger via a merge request
{: .fs-8 }
Get your own copy of someone else's material, so you can make changes and send them back for review as a merge request
{: .fs-6 .fw-300 }
---
This bit has a few stages, but git error messages and the GitLab web interface are here to help you out.
Coming soon
{: .label .label-yellow }
**This documentation needs to be updated for GitLab**
In this example I'm going to add some text to a repository that I do not own and I am not a contributor to.
For background, the repository is [Open Brain Consent](https://open-brain-consent.readthedocs.io/en/stable/index.html), which describes practical considerations and solutions relating to the open sharing of brain imaging data (my research field). I've been chatting with the repository owners, and they are expecting me to make this contribution 😊
## 1. Fork their repository
Once you have found the documentation you want to contribute to, you need to locate it on GitHub. Many sites will have a handy "Edit on GitHub" link (or something similar), particularly if they *want* you to contribute.
When you have found the GitHub repository, you need to "fork" it, to create a copy in your own GitHub account.
![gif-fork-repo](../../img/gifs/fork-repo.gif)
## 2. Clone your online copy to your local computer
Now you have an online copy of the code, you need to bring it down to your local computer with the "clone" command.
Get the https address of the repository you want to clone via the "code" button, click the "copy" button, then past the address into your command line application at the end of the command below:
`git clone [https-address]`
![gif-fork-repo-clone](../../img/gifs/fork-repo-clone.gif)
## 3. Create a branch
Before you start editing your local copy, it is good practice to create all your edits on a separate "branch" of the code. Creating a new branch makes a unique set of code changes with a unique name, and your branch may have multiple commits. Separating your edits onto a new branch makes it easier for the repository owner to isolate the changes you have made and integrate them into your repository with confidence.
Create your branch by entering the command below, replacing `[your-branch-name]` with something which broadly identifies the changes you are going to make.
`git checkout -b [your-branch-name]`
![gif-create-branch](../../img/gifs/create-branch.gif)
## 4. Make and push your changes
Now you can set about making your edit!
First confirm you are working on the new branch with the command below:
`git branch`
Then open your text editor and make and save the changes.
Finally, add, commit and save the changes as described in the earlier [git basics](2-4-git-basics.md)
Notice the git gave me a helpful error which told me that it din't know where to push my changes - there was not "upstream branch" - and very kindly told me what commands I need to enter to set the upstream to be this branch on my copy of the repository. Thanks, Git.
![gif-make-edits-to-forked-repo](../../img/gifs/make-edits-to-forked-repo.gif)
## 5. Submit your pull request master
Once your changes have been pushed, GitHub online will tell you that your copy and your branch are "ahead of" (have more changes than) the original repository. You can compare the changes and submit your pull request if you are happy with them!
![gif-pull-request](../../img/gifs/pull-request.gif)
Note that depending on how long it has been between you forking the original repository and submitting your pull request, you may have become out of sync with the original if there has been more work done on it. Follow the instructions [here from "7. Sync your forked master branch"](https://www.freecodecamp.org/news/how-to-make-your-first-pull-request-on-github-3/) to get yourself back in sync before submitting your pull request.
## 6. Wait for your pull request to be accepted!
If you're feeling excited by all this wonderful collaboration, jump back into the original repository you cloned from, and check that the pull request is there. You can even write something nice to the repository owners, if you're feeling friendly.
![gif-pull-request-confirmed](../../img/gifs/pull-request-confirm.gif)
Your pull request will now be reviewed by the repository owners, and you will get an email if/when it has been accepted. Now you have left a comment, you will also be notified when there are additional comments added to your thread.
Sweet! Now you know how to contribute to other people documentation hosted on GitHub! Lets crack on and have a go at doing it in a very safe space... This repository!
---
layout: default
title: 3.3 Play with this page
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 10
---
# Practice submitting your pull request to update this page
{: .fs-8 }
A safe space for you to submit changes to this very document!
{: .fs-6 .fw-300 }
---
## Let's play!
This page is a safe space for you to practice contributing to documentation. I was far more intimidated by the prospect of inserting my words into someone else's work than I was creating my own from scratch, so for these tutorials I've decided to show you things this way round - contribute first, then make your own.
Once you have contributed to someone else's documentation (and seen how easy it is), you may find it easier to envisage your own work as a collaborative, community effort (assuming that's what you are after), and help ease others into the contribution process.
Coming soon
{: .label .label-yellow }
**This documentation needs to be updated for GitLab**
## What to do
Below is a list of numbers. For your first contribution to someone else's documentation, I would like you to write your name, your pronouns, today's date, and your GitHub profile link against one of these numbers. If you don't know your profile link, click your profile icon (top right side) and open 'Your Profile' in a new tab. You can use the URL of that page to build your GitHub profile link. Use the link format: `[Link text here](LINK URL HERE)`. If you want to get jazzy, you can do something more complicated, like add a picture or some formatting! I invite you to freestyle or keep it functional as you wish.
Use the procedure described earlier to [fork, clone, branch, edit, push, and submit a pull request](3-2-fork-their-repo.md) to update the lines below.
We're going to assume we're in a "class" setting right now, and I'm expecting your pull requests to come in. I'll accept them as soon as I can! If we're not in an active tutorial, I'll still aim to get to them as soon as I can, but please accept my apologies if it is not instantaneous. Often collaboration is asynchronous!
When I have accepted your pull request, you will have a permanent (version controlled!) reminder of your first contribution 😃. Can you see how excited I'm getting about this!? So many !!! 😝
## Add your name and date here
We, the undersigned, have submitted a pull request to this repository:
> Pro tips:
> 1) To find the right page in this repository (or your copy of this repository) to edit, click on the "Edit this page on GitHub" link at the bottom of this page.
> 2) When you are adding your name, pronouns and date, delete the "&lt;br&gt;" next to the number you are updating. This is an html line break, so the list is vertical even when there are no entries. Without these "&lt;br&gt;" after each number, markdown tries to be be clever and put them all in one line for you. Sometimes useful, but not right now.
1. <br>
2. <br>
3. <br>
4. <br>
5. <br>
6. <br>
7. <br>
8. <br>
9. <br>
10. <br>
## You did it!
Congratulations! You just contributed to shared documentation! The documentation is now 1000 times better because you added your insight (maybe, probably)! You should do this more often, and help make stuff easier for other people to understand, and distribute the efforts of keeping good documentation relevant! Great job ⭐️
---
layout: default
title: 4.1 Make a repository
parent: Git and GitLab
grand_parent: Open WIN Tools
has_children: false
nav_order: 11
---
# Make a GitLab repository
{: .fs-8 }
Make your own basic documentation repository
{: .fs-6 .fw-300 }