Contributing to the Code in Flow Projects

/1 Comment/in /by

One of the coolest things I’m seeing as UnofficialSF grows is admin turning into beginner developers and beginner developers turning into better and better developers.

A key milestone on this pathway is creating your first pull request. A Pull Request is a very badly named thing that should be called a Code Submission. It represents someone saying “I’ve improved at least one code file of an existing project, and here are the improvements. If the maintainer of the project is comfortable with the changes, they should merge them in”.

For the Flowhana to achieve its full potential, we need more members to break through and get comfortable creating pull requests.

Here’s the basic trail….

Before Starting

  1. First of all, don’t worry that you’ll mess things up. Pull Requests sit atop a framework that has been developing over the last 20 years called git, and it ensures that no matter what happens, any change you make to the code can always be undone. There are tons of checks and balances. You can always throw stuff away and start over without losing any of your actual code.
  2. Secondly, don’t worry that your code isn’t good enough. Every developer starts out as a beginner. This will be a very friendly environment and you’ll learn a ton.

Learning the Basics

  1. Go to the repo (repository of code) up on Github that most interests you and look around. Get a feel for the features and how it’s structured. Get a github account if you don’t already have one.

2) Go through this tutorial, which provides a quick, simple introduction to the three core concepts: repos, branches, and pull requests.

3) Make an initial decision about what tools you’re going to use on your computer to manage your local copies of various code repositories. The big choice is whether you want to go with the command line or use a visual tool, and, if you want to use a visual tool, whether you want to us the VSCode tool that Salesforce recommends for development or a more git-centric tool like Github for Desktop. My recommendation is to use the command line if you’re already comfortable with managing things via the command line, but otherwise try Github for Desktop. VSCode is great for development but not quite as easy to get started with for git usage.

4) Next, explore the idea of remote and local repos. Github maintains the current “master” version of several repos that are associated with unofficialsf. When you want to work with one of them, you work with it on your local computer (from where you’ll do a bunch of deploys to Salesforce orgs). The process of creating a copy on your own computer so you can work with it is called cloning.

5) Next, study up on Branches. Branches are the heart of the collaborative model. Each branch is essentially a pointer to particular series of code changes. When you create a new branch ‘off’ of an existing code line, a junction is created and there are subsequently two different code lines. The rest of the community continues down the original branch while you get to make changes on your own code line. Ultimately, a Pull Request represents a request to merge your changes back into that existing code line that you originally branched off of. The number one thing that will make your initial experiences with code collaboration work better is to get a good understanding of branches and always know what branch you currently are on. To get a really good grounding of Branches, I recommend reading through the git book up through chapter 3.5. Even if you’re not using the command line, the diagrams alone are worth checking this out. It’s really useful to grok the idea that even though we metaphorically talk about codelines and tree-like branches, a ‘Branch’ is really just a pointer to a specific commit.

At this point, you’re ready to start contributing code to flow projects.

A quick note on forking. Forking a repo into your github account allows you to make changes without getting any access to the original repo. However, if you are interested in making contributions, don’t hesitate to ask for contributor rights on projects. When you’re a contributor, you still create branches and pull requests, but it’s a little simpler because you’re working with the main repo and not a forked copy. I welcome contributors to all of my repos.

So now we can discuss the core workflow you’ll use:

  1. identify a needed change in an existing project/repo
  2. if you don’t already have a local copy of the repo from a previous clone or fork, do a clone or fork.
  3. deploy your local copy to a dev org where you can work with it (see “Deployment, Orgs and SFDX” below)
  4. Create a working branch, make changes to the code and flows, and deploy the changes to your dev org. Frequently commit and check your code changes into your local repo, and periodically push your local repo to your github repo so you’ve got a safe copy up there. Iterate until you’re done.
  5. if your work includes apex code, add one or more test methods to test your work
  6. when you’re done, make sure all of your changes are pushed up to the github master repository on your working branch.
  7. create a pull request, indicating that you’re suggesting that any changes between your working branch and the current master branch be resolved by merging in your changes.
  8. wait for a review. someone like me will look at the code and possibly give you feedback.
  9. Ultimately, when the code is ready, someone with merge rights will merge your changes into the master branch of the master repository.

Deployment, Orgs and SFDX

We highly recommend using SFDX as part of your development process. It’s important to keep SFDX and all of the above stuff distinct, though. The above stuff is about code management and git, and sfdx is about salesforce org and metadata management. They work together really well, but you have to take it one step at a time.

If you’re like me, when you get to step 4 and deployment, you’ll use sfdx to create temporary dev orgs called scratch orgs where you can deploy and test in isolation. YOu’ll take advantage of super useful tracking built into sfdx that allows you push code up from your local machine and also make declarative changes (like building a flow on the org in Flow Builder) and then pull the metadata down into your local machine’s repo, so that all the changes are always together.

It’s also possible to do deployments the old way with packages and workbench.

To learn more about sfdx, start here.

Finally

There’s a lot here. Don’t rush it. I would recommend looking at this as a sort-of 1 year course of learning. When you get frustrated, take a break. search stack exchange when you run into problems. Enjoy the journey.