CreativeTech Wiki (internal)

Explore

Processes

Flex Suite Code Flow Process

FlexEngine Workflow

Welcome to the NEW Flex Suite workflow. This new workflow is intended to help you manage Flex Suite code from a Git repository and work locally.

To being working with Flex Suite code, study the image to the right. This image represents the flow of code for the Flex Suite. Notice that all code flows DOWN from the main branch to the several types of feature branches. Then the code ultimately flows DOWN to the dev branch. Note that the actions for moving data from main occurs through merges, yet the code moves UP to main via pull request.

All code will now be managed in this MonoRepo. Do not make edits direct in GAM anymore.

This is our virtuous code cycle for the Flex Suite.

⁠

⁠

Managing Flex Suite Code

SETUP

Create a new work branch for your feature, defect or hotfix from the main branch. ALWAYS create new features branches from main.

WORK

Do all of your work inside your new branch. Announce in the #ad-formats channel what unit you’re working on. (NOTE: Never merge any branch into your work branch, except main.)

TEST

Once your work in completed:

Commit and push your changes.

Merge your changes into the dev branch and resolve any conflicts.

Test your changes locally in the dev branch and if the feature works as expected, copy the relevant code to GAM.

Test in the GAM dev unit and follow the standard internal/external QA process.

If changes are required from QA, make your change on the original work branch and repeat step 3 until your ticket is approved. (NOTE: Do not make changes on dev IF you can avoid it.

See Below.⁠

)

READY FOR PRODUCTION

Once your ticket is approved and you’re work is ready for production, do a pull request on your work branch. This branch will be reviewed and if approved, the changes will be merged into the main branch.

Once your worked has been merged into main, checkout and pull the change from the main branch, then copy/paste your code from the main branch to the GAM production unit. (NOTE: Do not copy/paste to a production unit from anywhere but main.)

If you don’t know what to do, review the workflow image above. It defines your next steps from beginning to end.

Branch Definitions

There are three main branch types.

main

This branch is our source of truth. It represents all code that is currently in Production. It should exactly mirror GAM prod units.

NEVER merge your code into main. Code is always merge into this branch via pull request.

dev

This branch is a “disposable” merge branch where we can all merge our code for testing. It is intended to be a branch where code is merged together prior to release release for testing and QA.

NEVER merge the dev branch into any branch.

feature (defect, hotfix)

feature branches are where you create your code. It is always created and updated from main.

NEVER merge anything into your feature branch, except for he occasional main branch update.

Creating feature Branches

To create a feature branch, be sure that any code you’ve been working on is committed and you’re ready to start a new feature. If ready, follow this simple git flow to create your new feature branch:

git status

// Ensure you have no staged changes and are ready to start a clean new branch.

git checkout main

// Checkout the current main branch.

git pull

// Pulls the latest changed from the main branch. There should never be conflicts on this pull.

git checkout -b ADPLXXXX_MyNewFeature

// Creates a new branch from main, ensuring you have the latest production code.

NAMING CONVENTIONS MATTER.

Follow our branch naming convention when naming your branch. Be expressive, but concise.

Ex: ADPL1458_PageviewIdUpdateForTa

(Pay attention to the syntax. No dashes after ADPL. Pascal case the summary.)

Updating a feature branch from main

git status

// Ensure you have no staged changes on your branch. You should have previously committed.

git checkout main

// Checkout the current main branch.

git pull

// Pulls the latest changed from the main branch. There should never be conflicts on this pull.

git checkout ADPLXXXX_MyNewFeature

// Now that you have an updated main, go back to your feature branch.

git merge main

// Merges main into your current branch.

Merging your changes into the dev branch

As you work, but sure you are committing often. These commits should be incremental so maintain stable code.

Here are some

best practices⁠

for committing your code and writing helpful commit messages that save you and your fellow developers time and effort.

Once all your changes have been added and committed to your branch, you are now ready to merge your feature branch into the dev branch.

git status

// Ensure you have no staged changes on your branch. If you do, you need to add and commit your changes by following the next three steps.

git add .

// Stages all changes for commit.

git commit -m "Your Message"

// Commits your changes. Make your commit messages meaningful in case you need to revert to an earlier commit in the future.

git push

// Pushes your changes to origin. If you get a "set upstream" message, run the command provided in the terminal. You should only get this type of message once.

git checkout dev

// Checkout the dev branch.

git pull

// Update the dev branch.

git merge ADPLXXXX_MyNewFeature

// Merges the changes from your feature branch.

git pull git push

// Pulls the latest updates (if any) and pushes your code to origin dev.

HELPFUL HINT: Always check your terminal after running a git command to check for success or error messages!

Guidelines for working on GAM DEV

You may work directly on the dev unit in GAM for small changes. This is intended for small testing changes.

You must still do your work on the "-dev" unit in the FlexSuite AND make sure your work is merged into the dev branch.

CAUTION: Your work may be overwritten IF someone is working on the same dev unit as you.

Once completed, your changes must be reverted OR added to the dev branch.

GOLDEN RULE: When your done working OR it's the end of the day, the dev branch unit MUST match the GAM DEV unit.

Making a pull request

If your code is ready for production, you need to get it into the main branch. We do this through a pull request, which is our last opportunity to make sure that your approved code can be deployed. Once your code is merged into main via pull request, your code in gam.html and gam.css is now ready to be copy and pasted into GAM.

Follow these instructions to start this process with a pull request:

Push your code

Make sure your feature branch is pushed into origin.

git status

// Ensure you have no staged changes on your branch. If you do, you need to add and commit your changes by following the next three steps.

git add .

// Stages all changes for commit.

git commit -m "Your Message"

// Commits your changes. Make your commit messages meaningful in case you need to revert to an earlier commit in the future.

git push

// Pushes your changes to origin. If you get a "set upstream" message, run the command provided in the terminal. You should only get this type of message once.

Initiate the pull request

Go to the

FlexEngine repository⁠

and you should see a orange/yellow notification box at the top of the repository code:

⁠

⁠

Click the Compare & pull request button to create your pull request.

Please be sure to tag and notify

@Michael Waskiewicz⁠

@Tanvir Haider⁠

(as back up) when your pull request is ready for approval. You need at least one approval in order to merge your branch into the repository’s main branch.

Do not approve your own pull request unless for extreme circumstances; Mike should be looped in when this action is taken.

Only once your code is approved and merged into main should you copy and paste your updated GAM HTML and CSS back into GAM.

Troubleshooting

index.html or config.json has a merge conflict when I merge with main.

⁠

⁠

If you see that index.html or config.json is appearing in your changed files list, run the following command in your terminal:

git update-index --assume-unchanged index.html config.json

This command will make it so these two files will no longer be watched for changes. Now when you run git status, the list of changed files should no longer include index.html or config.json.

⁠

⁠

I have a merge conflict when I pull in main into my local branch.

⁠

⁠

If you are running into a merge conflict when you pull in the main branch into your local branch, read the error message in the terminal. It will indicate what files you need to look at to resolve your merge conflict.

If you notice that it’s the config.json or index.html file that’s causing the merge conflict, make sure you’ve run the following git command in your terminal while you’re on your local branch:

git update-index --assume-unchanged index.html config.json

Now if you rerun git pull, you should be able to merge successfully and commit the merge into your local branch.

⁠

⁠

⁠

I can’t pull from main because it’s saying I have file changes that I didn’t make.

Sometimes you might run into a merge error that says you need to commit or stash changes to a file that you may not have touched.

⁠

⁠

If it’s a file you’re certain you didn’t modify in your work, it’s safe to run the following git command in your terminal:

git checkout <FILENAME>

This will disregard whatever git thinks is in these files. Rerun git pull and you should be able to successfully pull updates to those files.

⁠

⁠

I have a merge conflict with a file(s) that isn’t index.html or config.json.

Merge conflicts are okay! We’re bound to get them with so many developers working in the same repository. Resolving merge conflicts is best handled in your preferred IDE.

If you are using VS Code, you’ll notice the Source Control section will have a notification badge indicating the number of files you have with merge conflict. Review your changes versus the incoming main code, and accept or reject these changes based on what your work includes.

What's the difference between git pull and git pull origin main ?

git pull origin main fetches commits from the main branch of the origin remote (into the local origin/main branch), and then it merges origin/main into the branch you currently have checked out.

git pull only works if the branch you have checked out is tracking an upstream branch. For example, if the branch you have checked out tracks origin/main, git pull is equivalent to git pull origin main

⁠

Source⁠

⁠

FlexEngine Workflow

Managing Flex Suite Code

If you don’t know what to do, review the workflow image above. It defines your next steps from beginning to end.

Branch Definitions

Creating feature Branches

NAMING CONVENTIONS MATTER.

Updating a feature branch from main

Merging your changes into the dev branch

Guidelines for working on GAM DEV