diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e290329..f933a3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Firstly, thanks for taking the time to check out this guide and thinking about contributing! -The following is a set of guidelines for contributing to PHS technical documentation. As the back-end to the [PHS Data Science Knowledge Base documentation page](https://public-health-scotland.github.io/knowledge-base/docs/), there is specific requirements to ensure that the documentation is consistent and accessible. +The following is a set of guidelines for contributing to PHS technical documentation. As the back-end to the [PHS Data Science Knowledge Base documentation page](https://public-health-scotland.github.io/knowledge-base/docs/), there are specific requirements to ensure that the documentation is consistent and accessible. #### Table Of Contents diff --git a/Information Sharing/Dashboard Accessibility Guidance.md b/Information Sharing/Dashboard Accessibility Guidance.md index b44b90d..592d859 100644 --- a/Information Sharing/Dashboard Accessibility Guidance.md +++ b/Information Sharing/Dashboard Accessibility Guidance.md @@ -18,7 +18,7 @@ Consider the overall layout and usability of the dashboard. Dashboards should id ### Top Tips -* Try to minimize large areas of white space. +* Try to minimise large areas of white space. * Think about the tabbing/focus order whilst using a keyboard to navigate your dashboard. Make sure you can navigate using a keyboard only, in a logical order. * Think about where users expect to find certain information - such as instructions, data sources, and contact information. * Try not to repeat content unnecessarily. @@ -27,7 +27,7 @@ Consider the overall layout and usability of the dashboard. Dashboards should id ## Automated testing tools -There are a number of tools available for testing accessibility. Amongst the most useful are, including: +There are a number of tools available for testing accessibility, including: * Chrome browser extensions: * The [axe browser extension](https://www.deque.com/axe/browser-extensions/) is useful for running automated and guided tests on targeted web pages. Signing up to axe beta allows you to export results and run all automatic tests. @@ -41,7 +41,7 @@ There are a number of tools available for testing accessibility. Amongst the mos ## Code * Ensure that the language attribute is set to "en" (see [Language of page WCAG 3.1.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html)). -* Ensure the main heading is marked up as such (see [Info and relationships WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)), this is particularly important for each new "tab" or "page" you build within the dashboard. +* Ensure the main heading is marked up as such (see [Info and relationships WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)). This is particularly important for each new "tab" or "page" you build within the dashboard. * Headers (H1 to H6) should be used to denote content levels, not as a convenient way to style text. * Header levels should start at H1 and proceed in order as appropriate - for example, don't start at H2, with no H1 or don't jump from H1 to H3. * The visual appearance of headers should match the programmatic level - for example, H1 should appear more prominent than H2. @@ -63,7 +63,7 @@ There are a number of tools available for testing accessibility. Amongst the mos * arrows * shift * escape -* There should be a logical order to the tabbing sequence - this can be tested using tab (forwards) and shift-tab (backwards). You want to ensure that elements within the dashboard are focussed on in a logical order (see [Focus order WCAG 2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html)). +* There should be a logical order to the tabbing sequence - this can be tested using tab (forwards) and shift-tab (backwards). You want to ensure that elements within the dashboard are focused on in a logical order (see [Focus order WCAG 2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html)). * Check that any drop-down menus or pop-outs can also be navigated using this method. * There should be a means to navigate back to the original page. * Guidance for using inputs should be added. This guidance should be placed before the input object to be read by screen readers before the user encounters the object. @@ -71,8 +71,8 @@ There are a number of tools available for testing accessibility. Amongst the mos ## Links * All links should be encoded correctly as links (see [Name, role, value WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)). -* When writing a link, make it descriptive and front-load it with relevant terms instead of using something generic like 'click here' or 'more'. Generic links do not make sense out of context or tell users where a link will take them. They also do not work for people using screen readers, who often scan through lists of links to navigate a page. It's important the links are descriptive so they make sense in isolation. - * Bad: For further information click here. +* When writing a link, make it descriptive and front-load it with relevant terms instead of using something generic like 'click here' or 'more'. Generic links do not make sense out of context or tell users where a link will take them. They also do not work for people using screen readers, who often scan through lists of links to navigate a page. The links must be descriptive so they make sense in isolation. + * Bad: For further information, click here. * Good: View more information on good link practice. * Do not use the same link text to link to different places. * Think about the size of the link users need to select. For users with reduced motor skills, a one-word link could be very difficult to select. @@ -88,23 +88,23 @@ There are a number of tools available for testing accessibility. Amongst the mos * Images should have alternate text (see [non-text content WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) for more information). * Alt text should typically: * Be accurate and equivalent in presenting the same content and function as presented by the image. - * Be succinct. This means the correct content and function of the image should be presented as succinctly as is appropriate. Typically no more than a few words are necessary, though rarely a short sentence or two may be appropriate. - * NOT be redundant or provide the exact same information as text within the context of the image. + * Be succinct. This means the correct content and function of the image should be presented as succinctly as is appropriate. Typically, no more than a few words are necessary, though rarely a short sentence or two may be appropriate. + * NOT be redundant or provide the same information as text within the context of the image. * NOT use the phrases "image of ..." or "graphic of ..." to describe the image. It's usually apparent to the user that it is an image. And if the image is conveying content, it is typically not necessary that the user knows that it is an image that is conveying the content, as opposed to text. ## Chart design and layout * All chart elements should have sufficient colour contrast (see [Contrast (minimum) WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)). * Make sure your chart works in greyscale. - * Blue is a rich colour across types of colour blindness so is a good base colour for charts. + * Blue is a rich colour across types of colour blindness, so is a good base colour for charts. * If gridlines are to be used in graphs, they should always be grey. A good tone is #bebebe (R190 G190 B190). -* Dashed lines can be used for graphs but no more than two variations. +* Dashed lines can be used for graphs, but no more than two variations. * Avoid pattern fill. * Charts should have horizontal text, never vertical. Consider swapping the chart axis if long labels are a problem. * Double value axes should not be used. Use two charts instead. * Include instructions for interacting with charts. * Chart titles should be coded as text, not as images. Include a title above the chart to ensure that this is read by a screen reader prior to the chart. -* Output resolution should be set to take account of intended destination. If a chart is pasted from Excel into Word and resized, the image can become pixelated and font size can fall below required size. +* Output resolution should be set to take account of the intended destination. If a chart is pasted from Excel into Word and resized, the image can become pixelated, and the font size can fall below the required size. * Ensure that chart elements will not be clipped or hidden when users change display options - for example, text spacing, resolution, resizing, contrast (see [Reflow WCAG 1.4.10](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html) for more guidance, particularly around avoiding losing functionality beyond 400% zoom). * Do not do the following: * use colour alone to convey information (see [Use of colour WCAG 1.4.1](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)). Alternative options include: @@ -112,19 +112,19 @@ There are a number of tools available for testing accessibility. Amongst the mos * mapping values to shapes * splitting up charts * use subtle colour changes to indicate extreme outliers - * rely solely on sensory characteristics of components such as shape, color, size, visual location, orientation, or sound (see [Sensory characteristics WCAG 1.3.3](https://www.w3.org/WAI/WCAG21/Understanding/sensory-characteristics.html)) - * have internal scroll bars on large chunks of text o use borders and backgrounds for charts + * rely solely on sensory characteristics of components such as shape, colour, size, visual location, orientation, or sound (see [Sensory characteristics WCAG 1.3.3](https://www.w3.org/WAI/WCAG21/Understanding/sensory-characteristics.html)) + * have internal scrollbars on large chunks of text or use borders and backgrounds for charts * use text that is too small * use white space/images as padding - * map tool tips underlinked like links when they are not links. + * map tooltips are underlined like links when they are not links. ## Branding and corporate colours -The logo must be presented in accordance with PHS branding guidelines and style guide. The Public Health Scotland logo should be used. Logos of legacy organisations should not be used. +The logo must be presented following PHS branding guidelines and style guide. The Public Health Scotland logo should be used. Logos of legacy organisations should not be used. ### Colour palette for digital products -The below tables show the main and supporting colour palettes available within the PHS Brand guidelines. The tables show the name, swatch, and the hex and RGB values for recreating this colours within digital products. +The tables below show the main and supporting colour palettes available within the PHS Brand guidelines. The tables show the name, swatch, and the hex and RGB values for recreating these colours within digital products. #### Main colour palette @@ -146,6 +146,6 @@ The below tables show the main and supporting colour palettes available within t ## Alternative formats -* Provide a download option for data in a flat format, for example csv. +* Provide a download option for data in a flat format, for example, CSV. * If a chart is displayed, the option to hide or show and download the displayed data (after any selecting or filtering has taken place) should also be provided. * Table cells should be accessible via keyboard (tab). diff --git a/Posit Infrastructure/How to Access Posit Workbench.md b/Posit Infrastructure/How to Access Posit Workbench.md index fab0a62..5d6f6fa 100644 --- a/Posit Infrastructure/How to Access Posit Workbench.md +++ b/Posit Infrastructure/How to Access Posit Workbench.md @@ -7,19 +7,19 @@ ## New user -If you're new to Posit Workbench and require that for your role, a user account and relevant access is set up by DaS (which includes access to Posit Package Manager). This follows a similar process to 'Access to Data', and requires line manager approval and is subject to the [Acceptable Usage Policy](Acceptable%20Usage%20Policy%20for%20Posit%20Workbench.md). This includes the deactivation of inactive accounts, if this affects you, see [Deactived User](#deactivated-user). +If you're new to Posit Workbench and require access for your role, a user account and relevant access are set up by DaS, including access to Posit Package Manager. This follows a similar process to the 'Access to Data' process, requires line manager approval, and is subject to the [Acceptable Usage Policy](Acceptable%20Usage%20Policy%20for%20Posit%20Workbench.md). Accounts may be deactivated after a period of inactivity; if this affects you, see [Deactivated User](#deactivated-user). 1. Go to [ServiceNow](https://nhsnss.service-now.com/phs/) > Digital & Security > Service Catalog > Make a Request 2. Select 'Corporate Applications' as the Product or Service 3. Another dropdown will appear where you can select the appropriate Posit application. In this case, Workbench. -4. Complete the rest of the form, and attach authorisation from your line manager (similar to Access to Data process). +4. Complete the rest of the form, and attach authorisation from your line manager (similar to the Access to Data process). 5. Submit the request! ## Deactivated user As part of the standard licence management processes for Posit, to keep us compliant with our licence agreement, we regularly review activity across the platform. Where accounts are found to be inactive, you will receive communication about the deactivation of your account. This process maintains user settings and data, with reactivation prioritised to be expected within 48 hours. -To request reactivation email the Data Science team ([phs.datascience@phs.scot](mailto:phs.datascience@phs.scot)) **with your LDAP username** and this will be actioned. +To request reactivation, email the Data Science team ([phs.datascience@phs.scot](mailto:phs.datascience@phs.scot)) **with your LDAP username** and this will be actioned. ## Logging in @@ -35,7 +35,7 @@ The Posit Workbench server is accessed via a web browser. To log in, follow the ![Posit Workbench login screen](https://user-images.githubusercontent.com/45657289/186685760-da0d9dc6-cfe8-4afc-93fd-7afaaf6fd91d.png) -5. Enter your LDAP username and password (the same credentials you use to login to your computer). +5. Enter your LDAP username and password (the same credentials you use to log in to your computer). 6. Click the "Sign In" button (circled in red above), or press the "enter" key on your keyboard. @@ -47,8 +47,8 @@ The Posit Workbench server is accessed via a web browser. To log in, follow the 1. From the screen shown above, click the "+ New Session" button (circled in red above) -2. This will provide a popup with some options as shown below for how to set up your session: - - The 'Session Name' can be left as the default or you can provide something more specific for you to identify. This could be useful if you require multiple sessions open at once. +2. This will provide a pop-up with some options, as shown below for how to set up your session: + - The 'Session Name' can be left as the default, or you can provide something more specific for you to identify the session later. This could be useful if you require multiple sessions open at once. - The 'Editor' allows you to select an IDE (Integrated Development Environment): RStudio (default), Jupyter Lab, Jupyter Notebook, or VS Code. - 'Cluster' can only be Kubernetes - There is separate guidance for selecting a suitable session size in [Posit Workbench and Kubernetes](Posit%20Workbench%20and%20Kubernetes.md). diff --git a/Posit Infrastructure/Memory Usage in SMR01.md b/Posit Infrastructure/Memory Usage in SMR01.md index 5c95584..4129fd1 100644 --- a/Posit Infrastructure/Memory Usage in SMR01.md +++ b/Posit Infrastructure/Memory Usage in SMR01.md @@ -8,7 +8,7 @@ This document aims to provide users with information on the minimum memory requi Computer random access memory (RAM) gives applications a place to store and access data that are being actively used, and to do so quickly. -Executing an SQL query against a database will result in that data being read into your R session's memory in its entirety, and all subsequent operations on that data are performed *in-memory*. You therefore need to ensure that your session has access to sufficient free memory to hold the size of data you intend to work within your analysis. +When you execute an SQL query against a database, the entire dataset is loaded into the memory of your R session. As a result, all subsequent operations on that data are done in memory. It is essential to ensure that your session has enough available memory to accommodate the size of the data you plan to analyse. The following table presents various sizes of extracts from the SMR01 dataset, from 1 month's worth of data, to the whole of SMR01, along with the amount of memory required just to fetch these data into R, and the recommended amount of memory to request if you intend to work with a dataset of this size. diff --git a/Posit Infrastructure/Overnight Sessions.md b/Posit Infrastructure/Overnight Sessions.md index 3b60e7d..27dcef6 100644 --- a/Posit Infrastructure/Overnight Sessions.md +++ b/Posit Infrastructure/Overnight Sessions.md @@ -12,7 +12,7 @@ This automated process can be overridden by including the word "NIGHT" at the st ## Process to start a "NIGHT" session -A Posit Workbench session that a user would like to continue running past 7:15pm must be named with the word "NIGHT" **when the session is started**. The following steps must be carried out to ensure that the session remains open past 7\:15pm\: +A Posit Workbench session that a user would like to continue running past 19:15 (7:15pm) must be named with the word "NIGHT" **when the session is started**. The following steps must be carried out to ensure that the session remains open past the automatic shutdown time: 1. After successfully logging into Posit Workbench, the user will be presented with the following screen: diff --git a/Posit Infrastructure/Posit Support.md b/Posit Infrastructure/Posit Support.md index f4e1e2f..e3c9098 100644 --- a/Posit Infrastructure/Posit Support.md +++ b/Posit Infrastructure/Posit Support.md @@ -33,7 +33,7 @@ Public Health Scotland's Data Science team will be providing first-line support - **Check Access Permissions**: Ensure that you have access permissions to the server or specific data sets. Check with someone else in your team, or DaS (via [Service Now](https://nhsnss.service-now.com/phs/)) to confirm your access permissions. _All database connections that were available on the old server infrastructure have been migrated and made available for testing during UAT._ - **Check Browser**: Sometimes, the issue might be related to the browser you are using. This has been identified in a couple of areas already with Mozilla Firefox. Try using a different browser to see if the issue persists; all Chromium based browsers are tested and work as expected (i.e. Microsoft Edge and Google Chrome). -If you have followed these troubleshooting steps and the issue still persists, please raise a support request by providing the following details (you can also use this form to reach out with questions about the infrastructure).: +If you have followed these troubleshooting steps and the issue still persists, please raise a support request by providing the following details (you can also use this form to reach out with questions about the infrastructure): - Specific steps taken that led to the issue - Error messages or symptoms diff --git a/Posit Infrastructure/Quick guide to your Posit Workbench session.md b/Posit Infrastructure/Quick guide to your Posit Workbench session.md index 14735c4..17ee6f4 100644 --- a/Posit Infrastructure/Quick guide to your Posit Workbench session.md +++ b/Posit Infrastructure/Quick guide to your Posit Workbench session.md @@ -2,7 +2,7 @@ ## Who is this for? -* Every user of Posit workbench, regardless of expertise level. +* Every user of Posit Workbench, regardless of expertise level. * The information has been kept as basic as possible. ## What is this quick guide about? @@ -13,7 +13,7 @@ ## How much memory do I need? -Computer random access memory (RAM) gives applications a place to store and access data that are being actively used, and to do so quickly. This is referred as memory. +Computer random access memory (RAM) gives applications a place to store and quickly access data that are actively in use. This is referred to as memory. Your session needs to have sufficient memory available to be able to load the required data into memory and load the required packages. Use the table below as a starting point: | Number of rows | Number of columns | Session memory recommendation | @@ -25,13 +25,13 @@ Your session needs to have sufficient memory available to be able to load the re | <= 10 million | <= 10 | 65,536 MB (64 GB) | | <= 10 million | <= 100 | 786,432 MB (768 GB) | -During your session you can see how much memory you've used using the pie chart graphic on the Environment tab. Checking this when you use Posit Workbench will help you learn how much memory your typical sessions are likely to require. +During your session, you can see how much memory you've used using the pie chart graphic on the Environment tab. Checking this when you use Posit Workbench will help you learn how much memory your typical sessions are likely to require. ![Memory usage pie chart](https://github.com/Public-Health-Scotland/technical-docs/assets/110984847/338dd117-417d-4436-be3a-87347176adbc) Remember you can also remove unused data frames from memory as suggested in the "Coding with R Section" of the [Best Practice with R in Posit Workbench](Best%20Practice%20with%20R%20in%20Posit%20Workbench.md) document. -More detailed information on Knowledge Base: +More detailed information on the Knowledge Base: * [Memory usage when processing SMR01](Memory%20Usage%20in%20SMR01.md) @@ -46,8 +46,10 @@ The Central Processing Unit (CPU) is the primary component of a computer that ex * If you are running code that relies on parallel processing (things like matrix multiplications or complex statistical models) you could request 2 or more CPUs. Check to see if this speeds up the processing (and whether this compensates for the additional cost of 6p per hour per number of CPUs). ## What if my session needs to run overnight? -* Sessions are closed automatically at 9pm every evening. -* If you have work that needs to continue beyond 9pm you should add the word NIGHT at the start of the session name when starting that session. If you're working on a project, your project will also need the word NIGHT in its name. +* Sessions are closed automatically at 19:15 (7:15 pm) every day. +* If you have work that needs to continue beyond this time you should add the word NIGHT at the start of the session name when starting that session. If you're working on a project, your project will also need the word NIGHT in its name. +* See [Overnight Sessions](Overnight%20Sessions.md) for the full guidance. + ## How can I use less memory? Using the parquet file format from the `{arrow}` package uses less memory and is faster to write. @@ -74,14 +76,14 @@ my_iris_data <- read_parquet("my_iris_data.parquet", col_select = c(Species, sta ## Symptoms of not having requested enough memory/CPU: -If your session tries to use more memory than requested the session will close. Prior to this occurring you may notice that files can't be autosaved and the session becomes unresponsive. +If your session tries to use more memory than requested, the session will close. Prior to this occurring, you may notice that files can't be autosaved and the session becomes unresponsive. ## My profile is too small: how can I request more memory/CPU? * Your Kubernetes profile is initially set to 1 CPU and a maximum of 4096 MB of memory. -* If you find you need more CPU/memory [please complete this form](https://forms.office.com/e/VEutAJ8p9Y) +* If you find you need more CPU/memory, please complete [this form](https://forms.office.com/e/VEutAJ8p9Y) ## Further general information about Posit Workbench sessions: * [Best Practice with R in Posit Workbench](Best%20Practice%20with%20R%20in%20Posit%20Workbench.md) -* [Recommendations on Global Options in Posit Workbench RStudio](Recommended%20Global%20Options%20for%20RStudio.md) +* [Recommended Global Options for RStudio](Recommended%20Global%20Options%20for%20RStudio.md) diff --git a/Posit Infrastructure/Recommended Global Options for RStudio.md b/Posit Infrastructure/Recommended Global Options for RStudio.md index d4ce841..ea3c65c 100644 --- a/Posit Infrastructure/Recommended Global Options for RStudio.md +++ b/Posit Infrastructure/Recommended Global Options for RStudio.md @@ -1,4 +1,4 @@ -# Recommendations on Global Options in Posit Workbench RStudio +# Recommended Global Options for RStudio ## Purpose @@ -14,7 +14,7 @@ The Global Options window can be accessed from a Posit Workbench session through ### Workspace -The workspace contains all the objects (vectors, matrices, data frames, etc.) and their values that have been defined in the current R session. There are two options that can be set in the Global Options window that affect the behaviour of sessions and their workspaces: +The workspace contains all the objects (vectors, matrices, data frames, etc.) and their values that have been defined in the current R session. Two options can be set in the Global Options window that affect the behaviour of sessions and their workspaces: ![Global Options Menu in RStudio with Workspace highlighted](https://user-images.githubusercontent.com/45657289/212689097-9c1d3aed-0373-4d9f-9095-884d1651e0fc.png) @@ -32,9 +32,9 @@ However, there are two main reasons why you would not want to save your R enviro In the situation where a project's working directory contains a `.RData` file, by default, the contents of that `.RData` file will be loaded into the session's environment when opening the project. There are two main reasons why we would not want this to happen: -* By opening a project and restoring that project's `.RData` file, the data and variables that were saved in the file will be loaded into the R environment, replacing any data and variables that were already there. This can cause confusion for users because they may not be aware of the contents of the `.RData` file and how they relate to the current project. +* By opening a project and restoring that project's `.RData` file, the data and variables that were saved in the file will be loaded into the R environment, replacing any data and variables that were already there. This can confuse users because they may not be aware of the contents of the `.RData` file and how they relate to the current project. -For example, imagine you are working on a project that uses a specific dataset and a set of variables. You save the project and close your Posit Workbench session. Later, another user opens the project and this action, by default, restores the .RData file. However, this `.RData` file contains a different dataset and a different set of variables to those that the user is expecting. If they continue working on the project without noticing this, they may inadvertently be analysing the wrong data or using the wrong variables in their analysis. This can lead to incorrect results, wasted time, and confusion. +For example, imagine you are working on a project that uses a specific dataset and a set of variables. You save the project and close your Posit Workbench session. Later, another user opens the project and this action, by default, restores the .RData file. However, this `.RData` file contains a different dataset and a different set of variables than those that the user is expecting. If they continue working on the project without noticing this, they may inadvertently be analysing the wrong data or using the wrong variables in their analysis. This can lead to incorrect results, wasted time, and confusion. * The process of loading a `.RData` file into the R environment can, particularly if it is a large file, take a very long time. In fact, the Posit Workbench session will crash, if the amount of memory required to restore the `.RData` file exceeds the amount of memory available to the session. diff --git a/Python/Python Style Guide.md b/Python/Python Style Guide.md index 7a3732b..3f8b138 100644 --- a/Python/Python Style Guide.md +++ b/Python/Python Style Guide.md @@ -2,4 +2,4 @@ This document is a coding style guide for using Python within PHS. It is designed to allow enough flexibility for working on different projects, while maintaining consistency across the organisation and ensuring that code can be easily read and shared. -Those familiar with development in Python will be aware of [Python Enhancement Proposals (PEPs)](https://peps.python.org/). [PEP8](https://peps.python.org/pep-0008/) is considered the accepted style guide for almost all cases where Python is used, PHS is no different. As such, [PEP8](https://peps.python.org/pep-0008/) is the foundation to this with some additional guidance on how to use Python in a way that is consistent with the rest of PHS. +Those familiar with development in Python will be aware of [Python Enhancement Proposals (PEPs)](https://peps.python.org/). [PEP 8](https://peps.python.org/pep-0008/) is considered the accepted style guide for almost all cases where Python is used; PHS is no different. As such, PEP 8 is the foundation for this guide, with some additional guidance on how to use Python in a way that is consistent with the rest of PHS. diff --git a/R/How to Use renv for Reproducible Projects.md b/R/How to Use renv for Reproducible Projects.md index 3816ca2..f2190a7 100644 --- a/R/How to Use renv for Reproducible Projects.md +++ b/R/How to Use renv for Reproducible Projects.md @@ -22,7 +22,7 @@ Pre-requisite: a project (preferably version-controlled using git). #### Existing project 1. Open the project. -2. Call `renv::init()` to initialise renv within that project. This can take a while depending on the size of the project. +2. Call `renv::init()` to initialise renv within that project. This can take a while, depending on the size of the project. 3. Calling `renv::status()` should confirm the new 'lockfile' is synced with the project (i.e., contains details of all the required packages). 4. Commit the changes (additional files and folders) to version control. @@ -31,21 +31,21 @@ Pre-requisite: a project (preferably version-controlled using git). #### Adding (/removing) packages to the project 1. Install (or remove) the required packages, preferably with `renv::install()`. -2. Change the code, by adding (or removing) calls to `library()` or `require()`, or the package function calls themselves e.g. `dplyr::group_by()`. +2. Change the code by adding (or removing) calls to `library()` or `require()`, or the package function calls themselves, e.g. `dplyr::group_by()`. 3. Calling `renv::status()` will tell you there are changes that aren't recorded in the lockfile. 4. Calling `renv::snapshot()` will record any changes into the lockfile. 5. Calling `renv::status()` should now confirm everything's synced. 6. Commit the changes in the renv.lock file using version control. - - The `.gitignore` should have been updated to exclude files/directories that shouldn't be tracked but the `.gitignore` itself may need to be committed here. - - `.Rprofile` - A project level file that gets things running by calling the `activate.R` script. - - `renv/activate.R` - The code that gets the environment set up and does all the necessary background work. - - `renv.lock` - The description of the project's dependencies to be reproduced. + - The `.gitignore` should have been updated to exclude files/directories that shouldn't be tracked, but the `.gitignore` itself may need to be committed here. + - `.Rprofile`: project-level file that sources `renv/activate.R`. + - `renv/activate.R`: sets up the environment and performs the required background work. + - `renv.lock`: records the project's dependencies to reproduce the environment. ### Restoring the environment #### Using a project that has already had [{renv}](https://rstudio.github.io/renv/) initialised (e.g., when collaborating on a colleague's project) -1. Ensure the project is synced with the latest version-controlled repository (e.g., `git pull` from github). +1. Ensure the project is synced with the latest version-controlled repository (e.g., `git pull` from GitHub). 2. Call `renv::restore()` to make sure your local version of the project has all the required packages. 3. Calling `renv::status()` should now confirm everything's synced. @@ -53,15 +53,15 @@ Pre-requisite: a project (preferably version-controlled using git). ![renv-complete-workflow](https://github.com/Public-Health-Scotland/technical-docs/assets/33964310/391de4ef-c7d3-4a09-8eed-95c0f48b50eb) -[{renv}](https://rstudio.github.io/renv/) works by storing the exact versions of each package used within each project. This helps to isolate the project from any external changes that might have caused problems (e.g., updating/removing packages when working on a different project). Once [{renv}](https://rstudio.github.io/renv/) is initialised in a project it stays on unless deliberately turned off (see [Introduction to renv](https://rstudio.github.io/renv/articles/renv.html)). +[{renv}](https://rstudio.github.io/renv/) works by storing the exact versions of each package used within each project. This helps to isolate the project from any external changes that might have caused problems (e.g., updating/removing packages when working on a different project). Once [{renv}](https://rstudio.github.io/renv/) is initialised in a project, it stays on unless deliberately turned off (see [Introduction to renv](https://rstudio.github.io/renv/articles/renv.html)). -When you initialise [{renv}](https://rstudio.github.io/renv/) in a project (renv::init()) it searches the scripts for any calls to `library()`, `require()` or package function calls and identifies which versions of each package are in use from the versions installed in the user's package library.. The following files/folders are then added to the project: +When you initialise [{renv}](https://rstudio.github.io/renv/) in a project (`renv::init()`), it searches the scripts for any calls to `library()`, `require()`, or package function calls and identifies which versions of each package are in use from the versions installed in the user's package library. The following files/folders are then added to the project: -- The folder `renv/library`: this is used for storing the packages. If the project is version-controlled using git a `.gitignore` file will be written to `renv/`, so that this library is ignored when changes to the project are committed. +- The folder `renv/library`: this is used for storing the packages. If the project is version-controlled using git, a `.gitignore` file will be written to `renv/`, so that this library is ignored when changes to the project are committed. - The lockfile `renv.lock`: this stores the details of the packages (including the versions used). - The profile file `.Rprofile`: this is run automatically when the project is opened, to ensure it uses the packages stored in renv/library. -Caution: the packages stored in renv/library and detailed in the lockfile are frozen in time and won't benefit from bug fixes. To update to the latest versions of packages call `renv::update()` periodically, and make sure the code still works before recording the new versions in the lockfile using `renv::snapshot()`. If the code doesn't work with the new versions you can roll back to the versions in the lockfile using `renv::restore()` (for more info see [Introduction to renv](https://rstudio.github.io/renv/articles/renv.html)). +Caution: the packages stored in renv/library and detailed in the lockfile are frozen in time and won't benefit from bug fixes. To update to the latest versions of packages, call `renv::update()` periodically, and make sure the code still works before recording the new versions in the lockfile using `renv::snapshot()`. If the code doesn't work with the new versions, you can roll back to the versions in the lockfile using `renv::restore()` (for more info see [Introduction to renv](https://rstudio.github.io/renv/articles/renv.html)). ## Resources diff --git a/Version Control/GitHub Guidance.md b/Version Control/GitHub Guidance.md index 20a8f9c..a4467d3 100644 --- a/Version Control/GitHub Guidance.md +++ b/Version Control/GitHub Guidance.md @@ -38,7 +38,7 @@ The following rules should be followed in order to adhere to security and confid To ensure consistency of use within the organisation, some guidance on styling while using git and GitHub is outlined below: -- **Repos names** should be lowercase with hyphens, descriptive and unique. For example, if you need a repo for *time series*, the repo name should be specific enough to highlight the publication or team name, e.g. `tpp-time-series`. +- **Repo names** should be lowercase with hyphens, descriptive and unique. For example, if you need a repo for *time series*, the repo name should be specific enough to highlight the publication or team name, e.g. `tpp-time-series`. - **Commit messages** should be concise and meaningful. If you need to raise awareness of something particular, the pull request commentary could be a better place. - **Teams** can be used, although consider how broad the team can be to be most effective. Instead of creating a team for a publication, does the team or health topic have better coverage? - **README files** are automatically rendered on the first page when visiting the repo on GitHub. They are the perfect place to provide users an overview of the project and how to get involved, an example is given in the [r-project-structure repo](https://github.com/Public-Health-Scotland/r-project-structure/blob/master/README.md). Where possible, README files should be generated for each public repo.