CAUTION: This document is under constant draft change at the moment.
This is a hands-on tutorial that volunteer software developers reference to get setup in order to make contributions in a collaborative way. This was written to ensure that you (a developer/graphic artist, etc.) get trained on a professional approach to software development while improving the non-profit’s digital assets. The sections here are:
For this non-profit, the persona are: interns, hosts, mentors, donors. Each person goes through different status over time: prospective, active, inactive, alum.
Scroll down to watch the “What is YWAM” video. Click the volume icon to unmute.
When did YWAM (the parent organization) start? See https://youtu.be/Uz0EesM-G04
Scroll down the page to see the diagram summarizing the activities by phase:
Open a browser tab to the FAQ (Frequently Asked Questions) to see if you can answer the questions before revealing the answer. Kinda like a quiz.
Watch demo video of How to apply for a Converge intership [2:20] No sound. The Ruby system is not mobile-friendly (progressive).
https://www.youtube.com/watch?v=hSqbotfxZAA Dec 23, 2015
The system consists of several components, described by this system flow chart on Google (created using Lucid Chart)
A Salesforce org database used internally for administration.
a. Team: How to get more people to be aware of this (advanced training to make a difference)? What are the outlets?
b. John: Create videos for display in emails (instead of text) about next steps, etc. within a drip email sequence.
c. Mike Ko: Create automated test scripts to verify whether the system works “end-to-end” (for different personas), to identify whether the sytem still works after changes.
d. Mike Ko: Identify in test site CSS/HTML changes to media query, etc. to display mobile screen size.
d. Dan: Upgrade front-end server version upgrade (to Ruby, Postgres, TLS 1.2 for Braintree, etc.).
e. Wilson: Create instructions (this page) to enable volunteers to create a dev environment and contribute changes.
f. Dan/Wilson: Convert bash scripts and instructions to create a dev instance of Ruby server running on Ubuntu.
g. Kermit: To troubleshoot without worry, define manual procedures and scripts to create a stand-alone Saleforce Dev. instance (a “crash dummy”) containing metadata and filtered/cleansed data from production org sandbox:
### Developer (volunteer):
h. Enable and test disaster recovery.
i. PROJECT: To best communicate with student/interns, we need someone to research, propose, and then develop the best option for texting internationally to students, hosts, mentors, donors. Wilson said he and Kermit saw a company offering a good texting solution at Dreamforce. Texts can replace emails if they include links to static web pages or links with reminders to log in to dashboard to complete an activity.
j. Make introduction videos to each of the persona for display on the website and to make emails more “alive”.
k. Create training for mentors ?
l. Translations of the site into various languages. We have a team currently translating the site into Spanish. A LOT of their work is already done. At some point, I want to get a Volunteer Project posted to insert the “es:” text into the code. (BTW, all the training videos are also being translated to Spanish to be inserted into the videos too. That will be another project. The team in Colombia is translating those SRT files now.)
m. Architect a more secure way to maintain passwords and other secrets for team (Hashicorp Vault, etc.)
n. Propose one of your own.
If you haven’t used the tools mentioned here, we will train you so that you can contribute confidently.
John makes use of Zoom for group video conferencing that can be recorded. The Zoom Meeting ID is: 236-178-0585
From John, get an email invite to the Slack channel used by developers (join the channels):
Click the “Channels” heading on the left pane. Click on a channel name. Click on “Join Channel”.
Use your email to get a free GitHub account and let us know what your GitHub account name is. Then you can fork our GitHub to your own account. Create a branch under your account to make changes, then create a Pull/Merge Request.
We share sensitive info like passwords only on WhatsApp chat.
Saleforce Chatter real-time text message we use to make announcements that get sent out as emails.
Open an internet browser to visit the production webpage for the non-profit at:
Youth With A Mission - Ocean City New Jersey
The tech behind the website consists of several components (all free open-source):
Dragonfly for image editing
Code and documentation about the website is at this GitHub repository:
BTW The name “IPO” is a carry-over of previous branding, and kinda stuck. We should rename it someday.
Optionally, if you want to examine the repo off-line, on your machine, create a folder and clone the repo onto your local laptop.
Click the “Branch: master” and select the branch Dan is current using: upgrade-rails-4.0
That branch name will be different in the future.
README.md describes each component and installation process in more detail.
README.rdoc contains instructions for running on an Appl MacOS laptop. But since the system runs under Ubuntu in production, we are converting scripts and instructions to that OS, and assume that you are using a Docker or cloud image (running on Amazon Lightsail</a>, etc.).
Create a VPC instance within Amazon Lightsail or other bare-bones VPS (Virtual Private Server).
PROTP: Begin with the 512 MB RAM to practice loading, then move up as necessary.
TODO: In the future we will define files to use Docker with Kubernetes.
Create another user, deployer.
sudo adduser deployer --ingroup admin
Type in password when prompted with “Enter new UNIX password:”.
passwd: password updated successfully Changing the user information for deployer Enter the new value, or press ENTER for the default Full Name : Room Number : Work Phone : Home Phone : Other : Is the information correct? [Y/n]
Reboot and login as deployer to run the Bash script which installs software, configure it, and populate the database, and runs a smoke test to verify viability.
Copy the command to invoke the install script to your Clipboard (by triple-clicking this line before pressing command+C) this string:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/wilsonmar/DevSecOps/master/Ruby/ywam-setup-all.sh)"
Get on your VPC command line interface and press command+V to paste the command.
On Amazon Lightsail, you would need to first click on the orange clipboard icon, then paste in its form, then click on the CLI (black screen), then right-click to paste (on a Mac, press two fingers at once on the touchpad). Press Enter to run the command.
BTW The script is supposed to be idempotent because it erases resident folders from the previous run.
Get into Setup. 0:53
Search “Sandboxes”. 1:05
Note the number of each type of sandbox available. 1:21
Before typing in the Name field, click “Create From”. 3:32
PROTIP: Because upper-case ones sort to the top while lower-case all appear in the bottom, enforce naming standards. This can confuse sequencing of Dev01, dev02, etc. So do like Salesforce’s “Production” and always use Title capital casing.
Salesforce provides weekly production backup zip. It’s triggered by a scheduled job from a service account which receives emails when done. Currently, each backup consists of 330 csv files take 8.3 MB zipped. Unzipped its 107 MB. The output zip file is copied to an alternative cloud provider (Google Drive) because Salesforce only stores backup files 48 hours, with file name (from a default name such as “WE_00DG0000000ggbAMAQ_1.ZIP”) to this example:
Metadata (custom fields, reports, list views, workflows, etc.) is extracted to a name such as:
TODO: Use UTC.
Due to active changes, daily backups are maintained for 13 months (370 zip files). The assumption is that there is a lot of financial info in the backups.
TODO: Add to the name the number of days since Jan 1 of the year.
3rd party offerings:
The production Salesforce instance is https://studentmobilizationcentre.my.salesforce.com, but to avoid additional charges we are trying to keep the number of people accessing it. Named users in SF are first initial and last name with no space.
Daniel Bryan is the root System Administrator.
email@example.com “Program Volunteer”.
There is a secret repository holding passwords to the production site.
PROPOSAL: Volunteers use generic accounts rather than named ones. For example:
firstname.lastname@example.org has the SF Standard “Executive Assistant” role.
“tester.312” has permissions to conduct tests and view security settings.
“user.415” has permissions to view reports and add opportunities.
TODO: Map out users, their roles, and permissions.
The diagram here illustrates, on one page, how the various pieces talk to each other.
Your first exposure to Salesforce is likely the Salesforce Trailhead website https://trailhead.salesforce.com which provides anyone a free Trailhead account with up to 5 “hands-on org” in a “playground” to use while taking learning modules. The sample gallery developed by Salesforce Developer Evangelists can be loaded as Dev orgs through the App Exchange. Sample packages are “unmanaged” and can be altered when installed. There are also managed packages (such as the Non-Profit Success Pack) from Salesforce partners.
Each org (database) contains two types of information: master data values such as customer names and metadata (Apex coding, form layouts, and other configurations).
Those who have bought one of the various levels of licenses for production usage have a single PROD org instance. Administrators go into Setup’s Sandbox function to create copies of metadata in various types of Sandboxes (abbreviated SBX). Different levels of licenses come with different numbers of each type of sandbox. Dev (Development) Sandboxes are created so developers can add a few records specific to test what they are changing. Other types of Sandboxes contain data copied in. Dev Pro Sandboxes have up to 200 MB of test data. Partial Sandboxes hold a sampling of data for integration testing. Full Sandboxes contain a complete copy of production records and metadata.
Since it can take awhile to copy, an email is sent when it’s done. To get data records into Sandboxes, we export based on filters in templates define within the Salesforce website. The export process also sends an email.
The DataLoader utility is used to put data in Sandboxes. Because we are dealing with private production data, cleansing for duplicates and/or masking for privacy after export needs to done. Doing that directly in production provides for validation before committing.
Trraditionally, developers create Change Sets to patch metadata, and run Salesforce Apex tests and UI tests using Selenium or TOSCA/Flood.io before pushing changes through various environments.
In 2018, Salesforce made available DX (Developer Experience) that manages temporary Scratch orgs updated by metadata stored in a Git version control repository. Temporary means 7-30 days before they disappear automatically.
To provide testing scripts the test data they need, custom scripts are written to load the test data into Scratch orgs and Playground org.
QUESTION: Can the DataLoader put custom external test data into the Dev Sandbox?
QUESTION: Can the DataLoader put data into Playground orgs?
QUESTION: Can a custom package be created from a Sandbox?
Each developer makes use of their own Salesforce org to work. This can be a Developer Sandbox provided from the Administrator or a copy of the production Salesforce org. in a Salesforce Trailhead Playground org.
Draft a description of what the system will look like when you’re done. This can be a picture of an altered form or report.
Define commit messages for the sequence of changes. This can provide a roadmap for estimating effort and timelines.
Define the tests for each feature added or changed.
We believe in the advantages of a “test first” approach. Create test scripts to validate new fields that have not yet been created. If the change is removal of a field, write a “negative” test to verify the absence of the field among a list. Then code changes that cause the test to pass.
Run a test of the existing test suite to ensure that everything works.
Define what changes you would like to make, in small increments of commit
Create a branch, named beginning with your assigned user name followed by a dash and number.
Make changes to the test suite, and make commits.
Create a Pull (Merge) Request:
Please send a GitHub Pull Request to opengovernment with a clear list of what you’ve done (read more about pull requests). When you send a pull request, we will love you forever if you include test code. We can always use more test coverage. Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).
Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should contain a paragraph describing what changed and its impact:
git commit -m "A brief summary of the commit"
Change the test suite and make sure it runs to success.
Please consider the people who will read your code, and make code reable for them. We optimize for readability:
[1, 2, 3], not
[1,2,3]), around operators (
x += 1, not
x+=1), and around hash arrows.
Visually review with others while it’s in your unit test environment.
Check the new branch into GitHub (or whatever version control repository your team uses).
Others make comments on the code.
One of the leads moves the branch into a test org and run more tests.
One of the leads deploys the change into production, then run post-deploy tests.