From b3ce3006563311e74346aa4061fcbac58762ed1b Mon Sep 17 00:00:00 2001 From: kmoscoe <165203920+kmoscoe@users.noreply.github.com> Date: Tue, 12 Nov 2024 17:29:03 -0800 Subject: [PATCH] New procedure for syncing to stable release (#536) * Revert to gerund Though the style guide says to just use imperatives, "get started" just sounds weird. Also this is more consistent with "troubleshooting" * merge * merge * stable release * removed reference to fork * updated procedures * wee corrections * recorrect * wee changes * wee changes * remove branch sync procedures * corrections from Hannah --- custom_dc/build_image.md | 69 ++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 42 deletions(-) diff --git a/custom_dc/build_image.md b/custom_dc/build_image.md index df3fec9dd..029054215 100644 --- a/custom_dc/build_image.md +++ b/custom_dc/build_image.md @@ -41,84 +41,68 @@ If you want to pick up the latest prebuilt version, do the following: ``` ## Build a local image {#build-repo} - You will need to build a local image in any of the following cases: - You are making substantive changes to the website UI - You are ready to deploy your custom site to GCP -Rather than building from "head", that is, the very latest changes in Github, which may not have been tested, we recommend that you use the tested "release" equivalent of the stable Docker image. This release uses the tag `customdc_stable`, and is available at [https://github.com/datacommonsorg/website/releases/tag/customdc_stable](https://github.com/datacommonsorg/website/releases/tag/customdc_stable){: target="_blank"}. - -> **Note:** If you are working on a large-scale customization, we recommend that you use a version control system to manage your code. We provide procedures for Github, and assume the following: -- You have a Github account and project. -- You have created a fork off the base Data Commons `website` repo (https://github.com/datacommonsorg/website){: target="_blank"} and a remote that points to it, and that you will push to that fork. - - -### Sync a local workspace to the stable release +Building from the master branch includes the very latest changes in Github, that may not have been tested. Instead, we recommend that you use the tested "stable" branch equivalent of the stable Docker image. This branch is `customdc_stable`, and is available at [https://github.com/datacommonsorg/website/tree/customdc_stable](https://github.com/datacommonsorg/website/tree/customdc_stable){: target="_blank"}. -If you are using a version control system other than Github, you can download a ZIP or TAR file from [https://github.com/datacommonsorg/website/releases/tag/customdc_stable](https://github.com/datacommonsorg/website/releases/tag/customdc_stable){: target="_blank"}. +> **Note:** If you are working on a large-scale customization, we recommend that you use a version control system to manage your code. We provide some procedures for Github. -In Github, use the following procedure. +### Clone the stable branch only -1. If you want to reuse the root directory you previously created and cloned, skip to step 3. -If you want to create a new source directory and start from scratch, clone the repo up to the stable release tag: +Use this procedure if you are not using Github, or if you are using Github and want to create a new source directory and start from scratch. +1. Run the following command: 
    git clone https://github.com/datacommonsorg/website --branch customdc_stable --single-branch  [DIRECTORY]
-1. Change to the root directory: - + This creates a new local branch called `customdc_stable` set to track the Data Commons repo branch. +1. To verify, run: 
    cd website | cd DIRECTORY
+   git branch -vv
+ You should see output like the following: + + ``` + * customdc_stable 83732891 [origin/customdc_stable] 2024-11-06 Custom DC stable release (#4710) + ``` + Rather than developing on this default branch, we recommend that you create another branch. -1. Create a new branch synced to the stable release: +### Sync code to the stable branch +The following procedure uses Github. If you are using another version control system, use the appropriate methods for updating submodules and syncing. + +1. Switch to the directory where you have cloned the Data Commons doe: 
-   git checkout -b BRANCH_NAME customdc_stable
+   cd website | cd DIRECTORY
-1. To verify that your local repo is at the same version of the code, run the following command: - +1. Update files: ``` - git log --oneline --graph + git pull origin customdc_stable ``` - You should see output similar to the following: + Note that g`origin` here refers to the source `datacommonsorg/website` repo. You may be using another remote name to point to that repo. + You should see output like the following: ``` - * 52635c8 (grafted, HEAD -> branch1, tag: customdc_stable) ... - ... + From https://github.com/datacommonsorg/website + * branch customdc_stable -> FETCH_HEAD + Already up to date. ``` - Verify that the last commit in the output matches that listed in https://github.com/datacommonsorg/website/releases/tag/customdc_stable. - -1. Press `q` to exit the output log. - 1. Create and update the necessary submodules: - ``` - git submodule foreach git pull origin customdc_stable git submodule update --init --recursive ``` You should see output like the following: - ``` Submodule 'import' (https://github.com/datacommonsorg/import.git) registered for path 'import' Submodule 'mixer' (https://github.com/datacommonsorg/mixer.git) registered for path 'mixer' Submodule path 'import': checked out '7d197583b6ad0dfe0568532f919482527c004a8e' Submodule path 'mixer': checked out '478cd499d4841a14efaf96ccf71bd36b74604486' ``` -1. Update all other files: - - ``` - git pull origin customdc_stable - ``` - You will likely see the following output: - - ``` - From https://github.com/datacommonsorg/website - * tag customdc_stable -> FETCH_HEAD - Already up to date. - ``` ### Build the repo locally @@ -147,6 +131,7 @@ docker run -it \ --env-file $PWD/custom_dc/env.list \ -p 8080:8080 \ -e DEBUG=true \ +-v INPUT_DIRECTORY:INPUT_DIRECTORY \ -v OUTPUT_DIRECTORY:OUTPUT_DIRECTORY \ [-v $PWD/server/templates/custom_dc/custom:/workspace/server/templates/custom_dc/custom \] [-v $PWD/static/custom_dc/custom:/workspace/static/custom_dc/custom \]