Notice that this page has been deprecated in favor of the new PyDM Tutorial in the SRF space


Git

Git is a command line version control tool that we use in development so that multiple people can work on one file at a time without stomping all over each other's changes. I would strongly recommend reading though the quick git intro I used in college before continuing down this page; I found it really helpful when I was first learning, and it'll help provide a lot of context for what comes next.

The Ubuntu command line tutorial could also be of interest if you're not familiar with using the command line interface.

If you don't have internet, this is a dump of the resources taken on 6/26/20
Git – CS 61.pdfThe Linux command line for beginner | Ubuntu | creating.pdf


PyDM

PyDM is next generation EDM! EDM is, unfortunately, the program used to make the typical LCLS home panel (the display with buttons and read backs and things).PyDM is basically a combination of EDM and PyQt (if you don't know what PyQt is, it's what we use to make Python GUIs). The goal is to eventually migrate all existing Python GUIs to PyDM, and to make any new ones going forward in PyDM, all while version controlling them using git and GitHub. The following tutorial will walk you through making a change to an existing PyDM panel and going through the review process to release it into production.

Tutorial

We're gonna get our feet wet with PyDM by adding your own personal Dev Panel to the production Operations Dev Panel!

  1. Set Up GitHub
  2. Create a personal copy of the production software
  3. Make sure you're either in the freshly copied repo in lcls-srv01 or mcclogin (step two left us in rhel6-64 if you're taking that route, so just ssh over to mcclogin)
    1. If on mcclogin, make sure to type "bash" and then "source /afs/slac/g/lcls/tools/script/UENVS.bash"
  4. Type "mkdir [Your Name]" and head into that directory
     
  5. Type "designer &"
  6. Sometimes you get an error saying something about backup files. Ignore it(: In the window that pops up, click "Widget" and then "Create"
     
  7. In the Widget box on the left, scroll all the way down and drag a drop a PyDMShellCommand somewhere in the widget that popped up in the last step
  8. Right click anywhere in the widget that isn't the tiny shell command button, hover over "layout" at the bottom, and click "lay out in a grid"
     
  9. In the Object Inspector in the top right, rename that button something more descriptive by double clicking it, typing the new name, and pressing enter
     
  10. Right click the button itself and click "Change text..."
     
  11. Rename it something more descriptive and press enter
  12. In the property/value table in the middle right, scroll all the way down to "commands," double click the value box (it'll be blank at first, and then it'll be a button that says "Change String List"), Click "New", type "pydm ~/opsTools/devPanel/example/example.py", then click "OK". This will launch the production example panel! 
  13. Save this file as devPanel[Your Name].ui
  14. From here, open opsDevPanel.ui from the parent directory (~/[your username]/devPanel)
  15. Drag and drop a PyDMRelatedDisplayButton onto the newly opened devPanel.ui 
  16. Right click rename the button itself and its object name like before
  17. Add the path to your personal dev panel in your subdirectory and save
     
  18. Back in your terminal in the devPanel directory, run "pydm opsDevPanel.ui" and you should see your creation! Feel free to play with it until it looks good to you!


  19. Run "git status" to see what's changed. It should be opsDevPanel.ui and a new folder with your name
  20. Run "git add [YOUR NEW FOLDER]" and "git add opsDevPanel.ui", then run another git status. They should both be staged for commit
  21. Run git commit -m "adding [YOUR NAME]'s dev panel"
  22. Push those changes to Github
    1. If on lcls-srv01, run "git push origin main" and log in when prompted
       
    2. If on mcclogin, ssh to rhel6-64, re-navigate to the repo, and run "git push origin main"
  23. Back on your fork on GitHub, click "Pull Request"
     
  24. Click "Create Pull Request"
  25. Add slaclab/ops as a reviewer (by clicking on the gear and then searching), and then click "Create pull request"
  26. An admin will look at it to make sure that nothing important got deleted, and if they approve it, they'll merge it into production!

Afterword: Updating Your Personal Repo

Note that the tutorial didn't say anything about updating your personal copy if the production copy gets updated by someone else. There are two ways to do this, and it's really your choice which one to do.

GitHub Method

  1. In the SLAC Lab production repo, click "Pull Request" and then "New Pull Request"
  2. Click on "Compare across forks" and then pick your fork in the left hand drop down menu
  3. Click "create pull request", which will take you to the same page we had in the tutorial! The only difference here is that you don't need any reviewers because you're merging it into your personal fork.

  4. You can just immediately merge it in on the next page by clicking "merge pull request"


    Sometimes it'll say that it can't be merged automatically. This usually happens when you've edited the same file as one that got updated in production. One way to avoid this problem on GitHub is to always keep your fork's main up to date with production and do all your work in a different branch and just deal with the merge conflicts locally

  5. Using the steps in the tutorial, ssh into rhel6-64 and navigate to the repository you created with Matt's script and run "git --bare fetch origin main:main". Mine doesn't have output because it's already up to date, but yours should
  6. Back in your physics devPanel directory, run "git pull origin main", and that should be it! Again, your output will be different from mine because mine is already up to date.

Command Line Method

This will rely heavily on git remotes. If you'd like to learn more about them, check this out!

Pulling From the Local Production Copy

Assuming that you trust the custodian of the local production copy to keep it up to date, this method is probably the easiest.

  1. In your physics devPanel directory, run "git remote add upstream ~/opsTools/devPanel"

  2. Now you can just run "git pull upstream main" whenever you'd like to bring your local copy up to date with production!


Pulling from the SLAC Lab Production Copy

If you don't trust the custodian of the local production copy to keep it up to date, then you can connect your bare AFS repo directly to SLAC Lab's production repo.


  1. Using the steps in the tutorial, ssh into rhel6-64, navigate to the bare repo you created with Matt's script, and run "git remote add upstream git@github.com:slaclab/devPanel.git" (gotten from the SLAC Lab devPanel page, much like we got it for our personal forks in the tutorial)

  2. Now, similar to in the GitHub method, you should run "git --bare fetch upstream main:main"  (yes, I have an error message, but it's for stupid reasons. Yours should be fine)
  3. And now it's the same step as in the GitHub method, running "git pull origin main" from your devPanel physics directory.

Steps 2 and 3 will need to be run every time you want to update.

Next Steps

If you're interested in continuing with Python development in Operations (and I hope you are!), here are a couple things you could tackle as intro projects

Making a simple PyDM GUI

Probably the best place to start. If you look at opsDevPanel.ui (run "pydm opsDevPanel.ui"), you should see an "Example Dev Panel" button on it. If you click it, you'll launch a really simple GUI whose entire function is to print what it's doing. If you look in the example subdirectory, you'll see example.ui and example.py, which together make up that simple GUI. I created example.ui using designer in the exact same way we created our dev panels in the tutorial. The difference here is that the button on opsDevPanel.ui is a related display button that leads to a python file instead of a ui file (example/example.py – you can open it up in designer to see). If you look at example.py, you'll see the format for a PyDM GUI:

  • Blue: The name of your GUI (and file – whatever name you choose for your GUI, the python file should be [name].py)

  • Green: The names you gave the UI elements in designer. Note that PyQt is an actual thing out in the google-able world; I literally googled "pyqt button pressed" to try to figure out how to get the "someone clicked this button" signal and connect it to something

  • Red: The custom functions for that GUI! It can be anything you want, this is just an example of a GUI that prints out what you're doing, but you could make a GUI that calculates power or something

Anything not in a box is boilerplate and should be present in any PyDM GUI. There's also very helpful PyDM documentation that Matt and Hugo wrote if you really wanna dig into what all those other PyDM widgets you see in designer can do.

OOP

 If you're not familiar with Python and/or Object Oriented Programming, here's a nice guide I found that can help answer questions like "what is __init__?"

Converting an existing Qt4 Python GUI to PyDM

This should theoretically be straightforward (famous last words). It should largely be taking a Qt4 GUI, deleting its autogenerated *_UI.py file, and changing Qt4 syntax to Qt5 syntax.

Migrating an existing Python GUI to ~/opsTools and version controlling it using git/GitHub

Most current GUIs live in /usr/local/lcls/tools/python/toolbox, which is both impossible to find and massively bloated with garbage files. Not only that, but they're also version controlled with CVS, which is a much less robust version control system (it allows you to overwrite someone else's changes if you don't know someone else is working on it...)

Migrating them should really just be moving the files to ~/opsTools, creating a SLAC Lab repository for it, connecting it using Matt's script, and updating references to it (like in buttons and launchpad)