Documentation updates for researchers (WIP)

WIP updates to the OpenSAFELY documentation, following changes to our processes around repo creation, transfer, and management.

Author: KatieB5

docs/getting-started/how-to/create-a-code-repository-for-your-project/index.md

@@ -7,43 +7,10 @@
 
 You only need to create a code repository once for a particular project.
 
-Create a new research code repository based on the research template.
 
-1. In your web browser,
-   go to the [research code template repository](https://github.com/opensafely/research-template).
-1. Click the "Use this template" button
-   to begin the process of creating a new research code repository for you to work on.
-   The screenshot below shows this.
+To create a repository for your OpenSAFELY project, you can either:
 
-![A screenshot showing the "Use this template" button for the research code template repository.](../../../images/codespaces-template.png)
+- Have a new repository created for you in the `opensafely` GitHub organisation
+- Create a repository in your own GitHub account, and request to have this trasnferred to the `opensafely` GitHub organisation later
 
-There are several options given
-when creating a new repository from a template.
-
-Here is a quick explanation of the options:
-
-* If you are creating a repository for an OpenSAFELY project,
-  you should choose `opensafely` as the repository owner.
-* If you are creating a repository for testing OpenSAFELY out,
-  you should choose *your own GitHub user account* as the repository owner.
-* You can enter any name and description that you choose for your repository.
-* You can choose whether the repository visibility is public or private.
-* You do not need to select "Include all branches".
-* You can ignore the mention of "GitHub Apps from GitHub Marketplace"
-  in GitHub's instructions for creating a new repository from a template.
-
-If you are unsure of what to do,
-refer to GitHub's step-by-step instructions for [creating a new repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template).
-
-!!! warning
-    Creating a repository owned by your GitHub user account
-    will enable you to:
-
-    * work on your OpenSAFELY research code in Codespaces
-    * check that your research code works with the OpenSAFELY platform
-
-    **It will not allow you to run code on OpenSAFELY's platform.**
-
-    For that, you would have to request that your repository is transferred to the `opensafely` organization.
-
-    Approved OpenSAFELY users are able to create a repository within the `opensafely` organization directly.
+You can find more information about both of these options, and how to create a repository, in the [Creating a repository for a project](docs/repositories.md/#Creating-a-repository-for-a-project) section of the OpenSAFELY documentation.

docs/repositories.md

@@ -9,7 +9,23 @@ GitHub is the means by which code in the repository is passed to the server to b
 
 ## Repository visibility
 
-In accordance with the [Principles of OpenSAFELY](https://www.opensafely.org/about/#transparency-and-public-logs), we expect all code from all users to be made public. As technical users will know, a public GitHub repository is visible by anyone on the internet, but only specified people will have the ability to change it.
+In accordance with the [Principles of OpenSAFELY](https://www.opensafely.org/about/#transparency-and-public-logs), we expect all code from all users to be made public.
+
+By default, repositories will initially be public, visible to anyone. Repositories may be temporarily set to private, visible to members of the opensafely organization only, by request (see How to make your repository private, below).
+
+### How to make your repository private
+
+Contact [Tech Support](how-to-get-help.md/#slack) to request that your repository is made private at any time.
+
+If your request is approved, Tech Support will make your repository private and you will be notified once this has been completed.
+
+Private repositories will be made public after 12 months. Ahead of that, you can make a new request to extend the private visibility period for another 12 months.
+
+!!! info
+    A repository must be made public if it forms part of a publication.
+
+    Refer to our information on when you need to [make your code public](https://docs.opensafely.org/repositories/#when-you-need-to-make-your-code-public).
+
 
 ### How to make your code public
 
@@ -26,29 +42,73 @@ A repository must be made public if it forms part of a [publication](https://www
 !!! warning
     You should _never_ commit files or content that should not be made public to the repository. All committed files, whether on the `main` branch or on development branches, will remain in the git history of the repository even after they have been deleted. These might include for example patient- or commercially-sensitive data from other sources, internal institutional documentation or forms, and incomplete manuscript drafts.
 
-## Creating a repository for a new project
+## Creating a repository for a project
+
+### New researchers and projects
+
+When you are approved to start working on an OpenSAFELY research project, you will be added to the OpenSAFELY GitHub organisation. Within the OpenSAFELY GitHub organisation, you’ll be added to the researchers team.
+
+Contact [Tech Support](how-to-get-help.md/#slack) and ask them to create a new repository for your research, or transfer a repository from your personal GitHub account into the OpenSAFELY GitHub organisation (depending on your preference, and whether you have an existing repository to transfer).
+
+New repositories will be created with the settings listed in [Default opensafely repository settings](tbc) below. A transferred repository's settings will also be updated to match these.
+
+Repositories will initially be public, but may be (temporarily) set to private at your request. See [Repository visibility](#repository-visibility) to make the right choice for your study.
+
+### Established researchers and projects
+
+Contact [Tech Support](how-to-get-help.md/#slack) to request the creation of any additional repositories you require. Please provide a name for the repository when you make a request. Your repository name should be short but informative — browse [existing repo names](https://github.com/orgs/opensafely/repositories) for inspiration.
+
+All repositories will be created using the OpenSAFELY [research-template repo](https://github.com/opensafely/research-template). You can see a detailed breakdown of this repository’s structure in [Repository structure](#repository-structure).
+
+## Transferring your own repository to the OpenSAFELY GitHub organisation
+
+You may want to start work on a project before approval by creating a repository in your own GitHub account (see instructions for how to do this below).
+
+!!! warning
+    Creating a repository owned by your GitHub user account will enable you to:
+
+    - work on your OpenSAFELY research code in Codespaces
+    - check that your research code works with the OpenSAFELY platform
+
+    It will not allow you to run code on OpenSAFELY's platform. For that, you would have to request that your repository is transferred to the opensafely organization.
+
+### How to transfer an existing repository to the opensafely organization
+
+To request that a repository be transferred from your own GitHub account to the OpenSAFELY GitHub organisation, please contact [Tech Support](how-to-get-help.md/#slack).
+
+If your request is approved, Tech Support will make the transfer and you will be notified once this has been completed.
+
+The settings of any transferred repositories will be updated to match the default opensafely repository settings, listed below:
+
+- Deletion of branches on merge: enabled
+- Branch protection for `master` and `main` branches: enabled
+- Require a pull request before merging: disabled
+
+### Creating a research repository in your own GitHub account so that you can transfer it later
 
 For ease of use, we have created a research template that you should use for your study.
 Go to the [OpenSAFELY research template repo](https://github.com/opensafely/research-template) on GitHub.
 Click the green button that says <span style="background-color: green; color: white">&nbsp;**Use this template**&nbsp;</span>.
 
 Fill in the details:
 
-- **owner**: select your personal GitHub for testing/experimenting, or select the `opensafely` organisation for a bona fide OpenSAFELY-approved study. The repo can be transferred into the `opensafely` organisation later if needed.
-- **repository name**: It needs to be short but informative &mdash; browse existing repo names for inspiration.
-- **Description**: This will appear at the top of the repo on GitHub. No more than a sentence is needed as the repo should be explained fully in the README.
+- **owner**: Select your personal GitHub for testing/experimenting.
+- **repository name**: It needs to be short but informative &mdash; browse [existing repo names](https://github.com/orgs/opensafely/repositories) for inspiration.
+- **description**: This will appear at the top of the repo on GitHub. No more than a sentence is needed as the repo should be explained fully in the `README.md`.
 - **public / private**: See [Repository visibility](#repository-visibility) to make the the right choice for your study.
 - **Include all branches**: Leave unchecked.
 
 And submit. You will now be at the GitHub landing page for the repo.
 
+If you are unsure of what to do, refer to GitHub's step-by-step instructions for [creating a new repository from a template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template).
+
 You should also download a copy of this repo to your machine so you can work on it locally.
 This is necessary because you can:
 
 * develop your code using familiar editing tools
 * test and run code without disturbing other contributors
 
-To clone your new repository to your machine, [follow these instructions](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) which explains cloning both via GitHub Desktop or via the command line.
+To clone your new repository to your machine, [follow these instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) which explains cloning both via GitHub Desktop or via the command line.
 When this is done, you should have a folder whose name is the same as the repo on your machine.
 
 Note that if someone else wants to commit to your recently created OpenSAFELY repo, they may need to wait up to an hour for the necessary write permissions to be granted.