Merge pull request #44 from UCLH-Foundry/staging

Updating guidance

contribute/project_submission.md

@@ -19,32 +19,44 @@ To help people who are interested in your research to better understand what dat
 
 Once your submission has been approved, you can find the embed URL by navigating to your deposit's page and selecting 'Embed' from the menu. Copy the iframe tag and include this in one of the html or markdown files you create in Step 3.
 
-## Step 2: Clone our repository on GitHub
+## Step 2: Fork our repository on GitHub
 
-To complete the next steps you will need a GitHub account, which will enable you to take a copy of the site's code and later merge your changes back in. If you don't have one you can [sign up for free](https://github.com/join). You will also need to [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) on your personal device.
+To complete the next steps you will need a GitHub account, which will enable you to take a copy of the site's code and later merge your changes back in. If you don't have one you can [sign up for free](https://github.com/join).
 
-The source code for this site can be found on GitHub: [{{site.data.github.url}}](https://{{site.data.github.url}}). To copy the code to work with on your own device, clone the repository with your git client or via the command line: 
+The source code for this site can be found on GitHub: [{{site.data.github.url}}](https://{{site.data.github.url}}). To make a copy you can make changes to, you can fork the repository. You can do whatever you want with the forked copy once you've made it, and then create a pull request (see below) to have your changes merged back into the original code base.
 
-`git clone https://{{site.data.github.url}}.git`
+To start, make sure you're logged into your account, and then find the fork button on this site's GitHub repository and click "Create a new fork":
+
+![UCLH Research Discovery GitHub repository (fork)]({{'assets/images/fork_1.png' | relative_url}})
+
+In the form that follows, select your username from the Owner dropdown menu, then click "Create fork". A copy of the repository should then appear under your own username with a note beneath the title saying "forked from {{site.data.github.url}}".
 
 ## Step 3: Complete the project template
 
-Once you have cloned the repository, you will need to create a new branch as you will not be able to merge your changes directly back into the main branch. Choose a name that identifies you or your group, and the name of the project, for example:
+Once you have forked the repository, you can start adding your project. The pages for each project are kept in separate folders under `/_projects`. Start by creating a new folder for your project containing an `index.md` file.
+
+### index.md
+Whilst you might be used to making a new folder before creating the files that go in it, GitHub doesn't actually let you create an empty folder, so you need to create both the folder and your first file at the same time. Every project folder must include a file called index.md, which serves as the landing page for your project, so that's probably the best place to start:
 
-`git switch -c group-a-project-x`
+1. From the main page of the forked repository, select the `_projects` folder from the file explorer table. ![Select _projects]({{'assets/images/new_project_1.png' | relative_url}})
+2. From within this folder, click *Add file > Create new file* ![Add file > Create new file]({{'assets/images/new_project_2.png' | relative_url}})
+3. At the top of the page you'll see an empty box with the placeholder text "Name your file...". Enter the name of the new folder you'd like to create:<br>**The name of the folder will be used to generate the title for your project (see below for how to override this)**<br>![Enter a folder name]({{'assets/images/new_project_3.png' | relative_url}})<br> followed by a forward slash `/`, and then the name of the file `index.md`:<br>![Enter file name]({{'assets/images/new_project_4.png' | relative_url}})
+4. You can now start writing a lay summary of your project written in [markdown](https://en.wikipedia.org/wiki/Markdown) format in the text box below. You can include as much detail as you like, but you also have the option to add additional pages if you'd like to split things up into separate sections (see *Extra content* below).
+5. When you'd like to save your progress, click "Commit changes...". In the pop-up enter whatever short message you think is appropriate to describe the changes you've made, then click "Commit changes".
+6. To edit an existing file, locate and click on it in the GitHub repository's file explorer, then select the pencil icon from the right of the toolbar:![Edit file icon]({{'assets/images/edit_file.png' | relative_url}})
 
-The pages for each project are kept in separate folders under `/_projects`, where you will also find a template for creating new projects: `_project_template`. Copy this folder and name it after your project. The name of the folder will be used to generate the title for your project (see below for how to override this). As a minimum your project folder should contain two files:
 
-* index.md
-* authors.txt
+If you're new to markdown:
+* Whilst editing a mardown file you can switch between the *Preview* and *Edit* views to get a sense of how your markdown content is going to appear on the page.
+* This [markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to help you get started.
 
-### index.md
-Every project folder must include a file called index.md, which serves as the landing page for your project. This page should include a lay summary of your project written in [markdown](https://en.wikipedia.org/wiki/Markdown) format. You can include as much detail as you like, but you also have the option to add additional pages if you'd like to split things like discussion of the data analysis or how you protect sensitive data into separate sections (see extra content below). If you're new to markdown, have a look at this [markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to help you get started.
 
 ### authors.txt
-This file is simply a list of all the people you'd like to include as authors on the project. Their names will appear at the top of the page, and on the summary card shown on the website's home page.
+Your project folder must also include a list of people to be credited as authors on the project in a separate file called `authors.txt` with each name on a separate line. These names will appear at the top of the page, and on the summary card shown on the website's home page.
+
+Make sure you are in your newly created project folder before clicking *Add file > Create new file*.
 
-Each name should appear on a separate line.
+![Example authors.txt]({{'assets/images/authors_txt.png' | relative_url}})
 
 ### title.txt
 By default the title for your project will be derived from the folder name by replacing any dash or hyphen characters with spaces, and converting the result to title case.
@@ -54,8 +66,6 @@ If you'd like to override this, add a file called `title.txt` and write the titl
 ### Extra content
 If you'd like to split content across several pages, or include an embed link for your data, you can add extra content by including additional markdown or html files in your project folder. This content will appear in separate tabs across the top of the page. 
 
-**Please note**: Only files with .html or .md suffixes are included, anything else is ignored. This can be useful if you need to include assets (images, javascript, css etc.) such as those generated by quarto.
-
 The name of the file is used to generate the tab label for the extra content as follows:
 
 * The filename suffix (.md/.html is removed)
@@ -68,30 +78,23 @@ As an example, the tab label for `03_code-and_data.md` would be "Code And Data".
 
 Tab order is alphabetical (except index.md which always appears first). To determine the order in which tabs appear, use numbers at the start of your filenames (e.g. `01_methods.md`, `02_privacy.md`, `03_data.html`).
 
-## Step 4: Make a pull request
-
-To publish your project, you will need to merge the new files into the main branch on the GitHub repository. To do this you will need to push the branch you've created back up to GitHub and then submit a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). The pull request process allows us to review submissions before they are added to ensure they comply with our standards.
+### Assets
+The site builder only picks up files with .html or .md suffixes as extra content to be included as tabs on the project page, anything else is ignored. However, you can use relative links to include other types of assets in your pages such as images, javascript, css etc. For example, you could create a folder inside your project folder called images, where you can upload all of the images you'd like to include in your pages. To upload a file, select "Upload files" from the "Add files" dropdown menu.
 
-### Pushing your branch to GitHub
-If you originally cloned the code as described in step 2, you can push the branch you've created back up to GitHub as follows:
+### Quarto
+If you use Quarto to generate an html page, you will find it generates a whole folder of assets that need to be included. No problem, just include the Quarto assets folder in your project folder alongside the html file, and the relative links to those assets should still work.
 
-```bash
-git push --set-upstream origin <name_of_your_branch>
-```
-
-Then, if you open the repository in GitHub, you should be able to see your branch listed in the drop down menu labelled main at the top of the list of files. 
+## Step 4: Make a pull request
 
-Pushing to the repository triggers an automatic process which will generate metadata and prepend it to index.md. Once generated, if you're comfortable working with Jekyll, you can edit this metadata to do things like changing the automatically generated project title and tab labels.
+To publish your project, you will need to merge your new files back into the original GitHub repository. To do this you will need to submit a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). The pull request process allows us to review submissions before they are added to ensure they comply with our standards.
 
-### Submitting a Pull Request
 To open a pull request:
-* Select Pull requests from the top navigation menu
-* Click the green 'New pull request' button
-* Select main from the left hand side dropdown labelled base (this should already be selected)
-* Select your branch from the right hand side dropdown labelled compare
-* Click 'Create pull request'
-* Add a title and description, including any details you think may be relevant for somebody reviewing your changes
-* Then click 'Create pull request'
+1. Select Pull requests from the top navigation menu<br> ![Pull requests in the top nav menu]({{'assets/images/pull_request_1.png' | relative_url}})
+2. Click the green 'New pull request' button
+3. On the next page title "Comparing changes" you should see the base repository on the left (the original repository) with an arrow pointing to it from the head repository (your fork) on the right. Make sure the pull request is targeting the staging branch on the base repository (this should already be selected as the default option)<br> ![Original repository on the left, fork on the right]({{'assets/images/pull_request_2.png' | relative_url}})
+4. Click 'Create pull request'
+5. Add a title and description, including any details you think may be relevant for somebody reviewing your changes
+6. Then click 'Create pull request'
 
 Your pull request will then need to be approved by two reviewers who are chosen automatically from a pool of volunteer editors. Reviewers might sometimes make comments or request changes before approving your submission so please make sure you are able to receive notifications from GitHub in order to respond to their requests.