Merge pull request #15 from UI-Research/etyagi

Add new content, CI/CD, etc.

.github/workflows/quarto-publish.yml

@@ -0,0 +1,29 @@
+on:
+  push:
+    branches: main
+
+name: Render and Publish
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          # To install LaTeX to build PDF book 
+          tinytex: true 
+          # uncomment below and fill to pin a version
+          # version: 0.9.600
+
+      # add software dependencies here
+
+      - name: Publish to GitHub Pages (and render)
+        uses: quarto-dev/quarto-actions/publish@v2
+        with:
+          target: gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions

.gitignore

@@ -1,4 +1,7 @@
-/.quarto/
 .Rproj.user
 .Rhistory 
-.DS_Store
+
+/.quarto/
+_site/
+
+.DS_Store

README.md

@@ -1 +1,38 @@
-# reproducibility-at-urban
+# reproducibility-at-urban
+
+This repository contains the code to build the [Reproducibility at Urban website](https://ui-research.github.io/reproducibility-at-urban). The goal of this site is to centralize resources to help staff across the Urban Institute adopt tools and practices to enable more reproducible research and workflows. 
+
+This site is built using Quarto. For an overview of setting up and developing websites with Quarto, see the [official documentation](https://quarto.org/docs/websites/). 
+
+## Adding or updating content 
+
+* To add a new page: Add the `.qmd` file to the root of the directory and update the `_quarto.yml` file with a link to the new page. 
+* To update an existing page: Update the relevant existing `.qmd` file. 
+* To update styling: Update the `styles.css` file. 
+
+You should always render and inspect your changes locally before pushing to GitHub (see instructions below). 
+
+## Local development 
+
+To preview local changes, use the following command from the terminal (or click the **Render** button in RStudio or VS Code): 
+
+```
+quarto preview
+```
+
+To render local changes, use the following command from the terminal: 
+
+```
+quarto render 
+```
+
+This will build the pages in the `_site` directory. Note that the `_site` directory should not be pushed to GitHub (and is ignored via the `.gitignore` file) because GitHub Actions will take care of building the site. 
+
+## Deployment 
+
+This repository uses GitHub Actions to build and deploy the site to GitHub Pages. Pushes to the `main` branch of the repository will trigger new builds. 
+
+**Note:** This uses Quarto's [freeze](https://quarto.org/docs/projects/code-execution.html#freeze) feature to only execute code locally. From the [Quarto docs](https://quarto.org/docs/publishing/github-pages.html#freezing-computations): 
+> If you have executable code in your project you’ll notice that a `_freeze` directory has been created at the top level of your project. This directory stores the results of computations and should be checked in to version control. Whenever you change a `.qmd` file with executable code, it will automatically be re-run during your next render and the updated computations will be stored in `_freeze`.
+
+If this causes issues down the line, we can also execute the code through the GitHub Action (but this will make the builds take longer and add complexity). 

_freeze/git-workflow/execute-results/html.json

@@ -0,0 +1,14 @@
+{
+  "hash": "a1b5964a32bf7b1c35b858fc303702ae",
+  "result": {
+    "markdown": "---\ntitle: Git and GitHub Workflow \nsubtitle: How to Use Git and GitHub at the Urban Institute\n---\n\n\nThis guide is intended to help Urban Institute employees get started with Git and GitHub. This guide assumes that you have already gone through the steps in the <a href=\"https://ui-research.github.io/reproducibility-at-urban/git-installation.html\" target=\"_blank\">Access and Installation Guide</a>. \n\nWe know that learning these tools can be a challenge, but we're here for you! Drop a message in the <a href=\"https://theurbaninstitute.slack.com/archives/C6J9AALDR\" target=\"_blank\">#github Slack channel</a> if you run into issues, and we will be happy to help out.\n\n## Using the command line \n\nThis guide shows how to use Git from the <a href=\"https://happygitwithr.com/shell.html\" target=\"_blank\">command line</a>, which may look scary but we promise will be useful to learn! There are other tools to interact with Git using a visual interface (like <a href=\"https://joshuadull.github.io/GitHub-Desktop/02-getting-started/index.html\" target=\"_blank\">GitHub Desktop</a>, or RStudio's built in Git integration). These tools may be helpful, but we recommend starting by reading this guide and understanding how Git works. Under the hood, all those visual interfaces just use the command line.\n\nTo run Git commands from the command line on a Windows computer, right click within any directory (i.e. folder) on your computer, and select **Git Bash Here**. Alternatively, if you already use an IDE like RStudio or VS Code, you can use the terminal within these IDEs directly to run commands. You can also read more about the command line in this <a href=\"https://happygitwithr.com/shell.html\" target=\"_blank\">tutorial</a>.\n\n\nThroughout this guide, `<>` indicate blanks that need to be filled in. Replace the `<>` with the desired text before you run the code:\n\n```{.bash}\nprint(\"Hello <name>!\") # if the guide says this\nprint(\"Hello world!\") # run this\n```\n\n## Basic workflow \n\n### The big picture \n\nBefore diving into syntax, keep in mind the big picture:\n\n1. Create a repository for a project. \n2. Tell Git which files to track. \n3. Take a snapshot of tracked files and add a commit message.\n4. Send those snapshots to a shared folder so others can access them. \n5. Repeat, repeat, repeat. \n\n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-workflow-v2.png)\n:::\n:::\n\n\n### Creating a new repository\n\n*This only needs to happen once per repository!*\n\n::: {.panel-tabset}\n\n#### Option 1\nUse this option if you do not already have a project folder on your computer and are starting from scratch. \n\n1. Under <a href=\"https://github.com/orgs/UI-Research/repositories\" target=\"_blank\">UI-Research</a> on GitHub, click the green button titled **New Repository** (top right corner). Give the repository a name, and click **Create Repository**. \n2. On GitHub, navigate to the repo that you just created and click the green button titled **Code** (top right corner). Copy the HTTPS remote URL. It will look like `https://github.com/UI-Research/<name_of_your_repo>.git`. \n3. Navigate to the directory where you want to keep the repo on your computer. Using the URL that you copied in the last step, clone the repository:   \n```{.bash}\ngit clone <remote_url_for_your_repo>\n```\n\n#### Option 2\nUse this option if you already have a project folder on your computer and want to turn that folder into a GitHub repository. \n\n1. Under <a href=\"https://github.com/orgs/UI-Research/repositories\" target=\"_blank\">UI-Research</a> on GitHub, click the green button titled **New Repository** (top right corner). Give the repository the same name as your directory, and click **Create Repository**. \n2. On GitHub, navigate to the repo that you just created and click the green button titled **Code** (top right corner). Copy the HTTPS remote URL. It will look like `https://github.com/UI-Research/<name_of_your_repo>.git`. \n3. Navigate to the root of your project folder and initialize a local repository:   \n```{.bash}\ngit init\n```\n4. Sync the URL for the remote repository that you copied in Step 2:  \n```{.bash}\ngit remote add origin <remote_url_for_your_repo>\n```\n\n:::\n\n### Cloning an existing repository\n\n*This only needs to happen once per repository per computer!*\n\nIf you want to clone a repository that already exists on GitHub to your computer: \n\n1. On GitHub, navigate to the repo, and click the green button titled **Code** (top right corner). Copy the HTTPS remote URL. It will look like `https://github.com/UI-Research/<name_of_your_repo>.git`. \n2. Navigate to the directory where you want to keep the repo on your computer. Using the URL that you copied in the last step, clone the repository:   \n```{.bash}\ngit clone <remote_url_for_your_repo>\n```\n\n    \n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-workflow-commands-v2.png)\n:::\n:::\n\n\n### Adding collaborators to a repository\n\nTo share the repository with others, navigate to the GitHub page for the repo. Then, click **Settings** (along the top) and **Collaborators and Teams** (along the left side panel). Click the relevant buttons to add people (individual users) or teams (groups of users). \n\nTeams are useful if you have a set of users who will all need access to multiple repositories. Creating a team saves you from having to add each user individually for each new repo. Urban has 50+ teams on GitHub for specific projects (e.g. `Education Data Team` for folks across TECH, COMMS, and EDP who work on the Education Data Portal) or teams or centers within Urban (e.g. `Data Science` or `HFPC`). \n\n### Basic commands and workflow\n\nThe most common Git commands you will use include `git add`, `git commit`, and `git push`. These tell Git which files to track, when to take snapshots of those files, and when to send those snapshots to GitHub for others to see. \n\n`git add` adds a file to Git's staging area. It tells Git, \"Hey, look at this file.\" \n```{.bash}\ngit add <file_name>\n``` \n\n`git commit` commits changes made to added files to the repository. It says, \"Hey, take a snapshot of the files I've added.\"\n```{.bash}\ngit commit -m \"<message>\" \n```\n\n`git status` prints out important information about your repo. Use it before and after most commands to understand how files have changed in your repo. \n```{.bash}\ngit status \n```\n\n`git push` pushes your local commits to the remote repository on GitHub. It says, \"hey, push all my snapshots to a shared folder so that other people can see them.\" The command below will push to the default `main` branch of your repo. Note that for repositories created before August 2021, the default branch was called `master`, instead of `main`. \n```{.bash}\ngit push origin main\n```\n\nBefore running the `git push` command, your code and commits could only be accessed on your local computer. \n\n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-github-workflow-v2.png)\n:::\n:::\n\n\n## Collaborative workflow\n\nThe main benefit of version control is making sure you and your collaborators are all using the latest and greatest version of your code. When working individually, this will just be your local version. When working with others, you should pull down the latest changes that anyone has pushed remotely before making further updates. \n\n`git pull` copies the latest changes that anyone has pushed remotely to your local repository. It says, \"Hey, replace my local version with the current version on GitHub.\" The command below will pull the latest version on the `main` branch. \n\n```{.bash}\ngit pull origin main\n```\n\n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-workflow-collab.png)\n:::\n:::\n\n\n### Branches  \n\nSo far in this guide, we've been working off a single `main` branch. By using multiple branches, you and your collaborators can update existing code or add new code without the fear of overwriting each others' files. Branches let you say \"Hey, I'm going to leave the main version of the code alone while I try some things out over here.\" \n\n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-branches.png)\n:::\n:::\n\n\n`git checkout` switches your local version to different branch. The `-b` flag in the command below tells Git to first create a new branch and then switch to it. When you first create a new branch, it will be identical to the local version of the branch that you switched from (typically the `main` branch). \n```{.bash}\ngit checkout -b <name_of_new_branch> \n```\n\n`git branch` will tell you what branch you are currently on. It's always a good idea to run `git branch` before pushing.  \n```{.bash}\ngit branch\n```\n\n`git push` sends your local commits to the remote repository, as noted earlier. To push to a specific branch, specify the branch name in the command. If you don't explicitly specify a branch, Git will push to whichever branch you are on.      \n```{.bash}\ngit push origin <name_of_new_branch> \n```\n\n### Pull requests \n\nWhen you're ready to share the updates on your branch with others, open a pull request. This says, \"Hey, I'd like to merge the work on my branch into the `main` (or some other) branch.\" Pull requests makes it easy for others to see the changes you've made and provide feedback. They also help organize multiple related commits into a single update. \n\nThe most common way to open, review, and merge a pull request is through GitHub, rather than from the command line. Different teams develop their own standards for branching and pull requests, but here's a common workflow:  \n\n1. From your repo, click **Pull requests** (along the top) and then click the green **New pull request** button. \n\n2. Select the branch with your work. By default, GitHub will create a pull request into the `main` branch.  \n\n3. Review the files that have changed to ensure you don't accidentally merge files you don't intend to into the `main` branch. \n\n4. Click **Create pull request**. Write a summary of the updates included in the pull request and why you made those updates. You can also add **Reviewers** (along the right panel) to notify others that you would like them to look at your changes. \n\n5. To make changes to the code included in a pull request if (e.g. if a reviewer requests updates), simply push to the same branch. The pull request will automatically be updated to reflect these changes. \n\n6. Once approved, merge the pull request into the `main` branch by clicking the green **Merge** or **Rebase and merge** button. \n\n7. Once your branch has been merged, delete it. \n\n\n::: {.cell}\n::: {.cell-output-display}\n![](images/git-workflow-branches.png)\n:::\n:::\n\n\nAfter merging the pull request, you should return to the `main` branch and sync your local directory with the merged changes:\n\n`git checkout` switches your local version to a different branch. \n```{.bash}\ngit checkout main\n```\n\n`git pull` copies the latest changes from the pull request that you just merged remotely to your local repository. If you don't explicitly specify a branch when running the `git pull` command, Git will pull from the branch you are currently on. \n```{.bash}\ngit pull\n```\n\n## Summary of commands \n\nThe table below summarizes the commands that we've discussed in this guide. There are also tons of Git cheat sheets available online (e.g. from <a href=\"https://education.github.com/git-cheat-sheet-education.pdf\" target=\"_blank\">GitHub Education</a>, <a href=\"https://about.gitlab.com/images/press/git-cheat-sheet.pdf\" target=\"_blank\">GitLab</a>, or <a href=\"https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet\" target=\"_blank\">Atlassian</a>). \n\n| Command                                  | What you're telling Git                                 | \n| ---------------------------------------- | ------------------------------------------------------- | \n| `git clone <remote_url_for_your_repo>`   | \"Hey, copy this remote project to my local computer\"    | \n| `git add <file_name>`                    | \"Hey, look at this file\"                                | \n| `git commit -m \"<message>\"`              | \"Hey, take a snapshot of the files I’ve added\"          |\n| `git status`                             | \"Hey, tell me about what you're looking at\"             |\n| `git push`                               | \"Hey, send my snapshots to a shared folder so other people can see them\" |\n| `git pull`                               | \"Hey, replace my local version with the remote version of the shared folder\" |\n| `git checkout -b <name_of_new_branch>`   | \"Hey, create a new branch and switch to it\"             |\n| `git checkout <name_of_existing_branch>` | \"Hey, switch to a different branch\"                     |\n| `git branch`                             | \"Hey, tell me what branch I'm on\"                       |\n\n## Parting advice \n\nPhew, that was a lot! If you're new to Git and GitHub, don't get bogged down in the details. Start by adding, committing, and pushing files to GitHub on the `main` branch. Once you're comfortable with those steps, find a colleague to work with you on the `main` branch and start pulling their updates. Before long, you'll have that workflow down and will be ready to start using multiple branches and opening pull requests. \n\nThis guide is meant to be an introduction. Git and GitHub have hundreds of useful commands and features not discussed here. Different folks and teams also have different opinions on workflows and best practices for using these tools. Once you have a grasp of the basics, we encourage you to start exploring to find a workflow that works for you. \n\nYou will inevitably run into errors along the way, but learning how to resolve those will make you a better researcher, programmer, and problem solver. Don't be afraid to ask for help – the <a href=\"https://theurbaninstitute.slack.com/archives/C6J9AALDR\" target=\"_blank\">#github Slack channel</a> is a great place to start! \n\nLastly, remember that if things ever go horribly wrong, you can use the inelegant (but effective) <a href=\"https://happygitwithr.com/burn.html\" target=\"_blank\">\"burn it all down\" technique</a> to return to a happy state: save your work elsewhere, delete the project folder, and clone a fresh copy of the repository. \n\n\n::: {.cell layout-align=\"center\"}\n::: {.cell-output-display}\n![](https://imgs.xkcd.com/comics/git_2x.png){fig-align='center' width=35%}\n:::\n:::\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}