Editing Atlas Hosted Aeon Web Pages in GitHub

Print Friendly and PDF Follow

For institutions hosted by Atlas Systems, web pages will now be maintained in GitHub repositories (repos).

Maintaining web pages in GitHub features many upgraded benefits. Some of these include:

  • Easy to contribute to your pages
  • Tracking changes across versions
  • Changes reflected in your live system within 1 minute
  • Ease of troubleshooting by locating the date and time when problems occurred
  • More flexibility for your local web development processes

Guide Navigation

Obtaining Access | Your Repositories (PCI Sites) | Web Page Layout | Downloading a Backup of Your Web Pages | Making Changes | Reverting Changes | Using Testweb | Initiating Code Reviews (PCI Sites) |  Version Control Systems 

Overview.png

Obtaining Access

Your repository has restricted access. Please contact support@atlas-sys.com to obtain permissions to the repository for your institution's web pages. You will need an account set up in GitHub for access. Atlas Hosting Services will send you a link to your repo when you are registered. This will allow you to edit and save (commit) changes to your web pages directly within the GitHub interface, as well as send your changes to the Atlas Development Team for a secure code review if your site is hosted in the PCI environment. Access is granted per individual, not per institution since individual accounts are required for tracking changes in GitHub. Please let hosting know if additional people at your institution require access to edit the web pages.

Your Repositories (PCI Sites)

Note: The following information is only applicable to Atlas-hosted sites in the PCI environment (those that use a credit card payment gateway). Non-PCI sites will only have one repository in Github and changes to web pages will not have to undergo the code review process.

Due to PCI requirements, all changes to your Aeon web pages must undergo a secure code review by Atlas staff before going live to patrons. To streamline this process, each institution will have two respositories in GitHub:

  1. A production repository (AtlasSystems-HS) maintained by Atlas staff that holds your production pages that are currently live to patrons.
  2. A forked repository (AtlasSystems) maintained by your institution's staff that contains your TestWeb along with a copy of your production pages for editing. 

Production Repository: AtlasSystems-HS

You will be given view access to the repository containing your live production web pages. This repository will contain the same name as your forked repository, with the addition of "-HS" after AtlasSystems in the name, for example:

AtlasSystemsHS.png

From this repository you can:

  • View your web pages currently in production.
  • View, close, or reopen pull requests.
  • Comment on existing pull requests.
Please note you cannot directly edit the files in the production repository.

Forked Repository: AtlasSystems

You will be given edit access to the repository containing your TestWeb and a copy of your production pages for editing. This repository will begin with "AtlasSystems" and will also have a branching icon and a note flagging it as a forked repository to help you distinguish it from the production repository:

Forked.png

From this repository you can:

  • Edit, view, and test your Testweb pages without a code review immediately after making changes.
  • Make changes to a copy of your production pages and submit those changes for review by Atlas staff before going live.

Pushing Changes Live: The Code Review Process (PCI Sites)

Because you cannot directly edit your production pages in the production repository, all changes to your web pages will undergo the following process before going live to patrons:

  1. Make changes to the copies of your production pages located in the forked repository.
  2. Submit a pull request within GitHub to Atlas staff to begin the code review process once all desired changes are made.
  3. Atlas staff will review your changes, and if approved, will merge your changes into the production repository to go live to patrons.

For more information on pull requests, see the Initiating Code Reviews section of this article.


Web Page Layout

The web pages structure may appear slightly different than the directory structure in IIS that you are used to. The file structure is flattened to a single level in the repo. For example, instead of clicking the Aeon folder then the Web folder and finally the testweb folder to access the Testweb web pages, the top level would be Aeon_TestWeb.

WebPageStructure.png

The tree under the README.md file shows the folder structure as it would appear in the server. 

FolderStructure.png

Repository Do's and Don'ts 

Your GitHub repository will give you a wide range of flexible options and tools for managing your web pages. However, there are a few restrictions and guidelines to keep in mind while editing your web pages in GitHub: 

Don't: Do:
  • Do not rename or move folders in the repository - This will break synchronization and your web pages!
  • Do not edit or delete webpath.txt.
  • Do not save backups of your web pages on the server in GitHub. 
  • Add, delete, or modify files as needed within the folders.
  • Consult Atlas Support if you need structural changes to the folders.
  • Save backups of your files locally on your workstation for safekeeping.

Downloading a Backup of Your Web Pages 

VTL_VideoLink.png

If you would like to make a backup copy of your web pages for safekeeping, these should be downloaded to your local machine rather than made within your GitHub repository. To download a copy of your web pages from GitHub to your machine, follow the steps below:

  1. Navigate to the homepage of your repository in GitHub.
  2. Click on the green "Code" button.
  3. Click the "Download ZIP" option from the dropdown menu. 

    Dropdown.png

  4. A copy of the files in your web directory will be downloaded to your workstation as a ZIP file. You can then store these files wherever you'd like on your machine for safekeeping.
PCI sites can download a copy of the web pages from either the production repository or the forked repository. Your production repository will always contain the version of the web pages currently live to patrons, while your forked repository will contain any changes you've made to the copies of your production pages that may not yet be live. 

Making Changes

VTL_VideoLink.png

You can edit pages directly within GitHub and these changes, when committed, are reflected within a minute on your Testweb server if the changes have been made to the files in the TestWeb directory. If making changes to the copies of your production pages, these will be made live to patrons immediately for non-PCI sites or after requesting a secure code review by Atlas staff for sites hosted in the PCI environment. Only changes committed to the main branch will be applied to the web pages at this time. However, you can work on other branches and commit changes prior to merging the work onto the main branch. 

Example

In the example below, we're going to remove the Photoduplication Request option from the navigation bar (include_nav.html). 

  1. Navigate to the appropriate web page in your repository. PCI sites should make sure to navigate to the web page in the forked repository. If you would like to test your changes on the Testweb server, make sure that you navigate to the correct file within the Aeon_TestWeb folder. 

    Edit_page.png

  2. Click the edit icon highlighted in the picture above.
  3. Make the appropriate changes.
  4. Scroll to the bottom of the pages and edit the comment box to describe the change(s) you made. Please include a title briefly describing the change in the title field.
  5. You can optionally add an extended description in the body of the change details.
  6. Click Commit changes, making sure Commit directly to the main branch is selected.

    Commit_changes.png

View Change History 

To see all the changes for a specific webpage:

  1. Navigate to the appropriate web page.
  2. Click the History button.

    Change_History.png

  3. Click the title of the change.

    Change_Title.png

Any changes/additions will be marked in green and any legacy formatting/verbiage and deletions will be in red. By default, the change view is Unified with both the previous formatting and the changes included in one view. See the image below.

Unified.png

To view the changes in a comparison format, click the Split button. See the image below.

Split.png


Reverting Changes

VTL_VideoLink.png

If you make a change to a web page, but then later decide you'd like to reverse the change that you made, you can use GitHub Desktop to quickly revert the web page back to its previous version. 

Step One: Download and Configure GitHub Desktop

  1. Download the GitHub Desktop application for your workstation.
  2. Navigate to the homepage of your repository (PCI sites should make sure to go to their forked repository).
  3. Click the green "Code" button.
  4. Click the "Open with GitHub Desktop" option from the dropdown menu.

    GitHub_Desktop.png

  5. A pop-up window may open in your browser asking you to confirm that you want to open the GitHub Desktop application. Confirm your decision and the application will open.
  6. If this is your first time opening the repository in the application, it will prompt you to sign in to GitHub and clone the repository to your machine. Follow the prompts to complete this process.
  7. Your repository should now be accessible on your machine through the GitHub Desktop application. Click "Fetch Origin" at the top of the application window to ensure you have the latest version of your repository on your computer.

    Fetch_Origin.png

Step Two: Find and Revert the Change in GitHub Desktop

  1. After opening your repository in GitHub Desktop, click "Fetch Origin" at the top of the screen to ensure that you have the latest version of the repository loaded into the application if you have not done so already.
  2. Click the "History" tab on the left side of the application window. 

    History.png

  3. Find the change that you want to revert in the History menu.
  4. Right-click on the change and select "Revert Changes in Commit" from the menu.

    Revert.png

  5. A new entry should appear at the top of the History tab noting that you reverted the change.

  6. Click "Push Origin" at the top of the application window to push the reverted change to your GitHub server.

    Push_origin.png

  7. Confirm that the change has been reverted by viewing the web page on your server. 

Using Testweb

Note: PCI sites should perform any changes using Testweb should be performed in the forked repository.

If you'd like to edit the pages in your Testweb first to see how they will work in the live system, simply edit those pages and they will be updated within 1 minute so that you can verify any changes before making them in the production pages.

For example, to edit the pages in your Aeon/Web/Testweb folder, you would find those pages to edit in the repo under:

Aeon_TestWeb

Loading a New Set of Default Web Pages into Testweb 

VTL_VideoLink.png

If you would like to load a new set of default web pages into your Testweb for previewing, testing, or customization, follow the steps below:

  1. Download the newest copy of default pages from the Aeon Downloads page.
  2. The pages will download as a zip file. Extract the files in the zip file to a folder on your workstation. 
  3. Navigate to your repository at GitHub.com, click the green "Code" button, and select the "Open with GitHub Desktop" option.

    See the Reverting Changes section of this guide for information on configuring GitHub Desktop.

    GitHub_Desktop.png

  4. A pop-up window may open in your browser asking you to confirm that you want to open the GitHub Desktop application. Confirm your decision and the application will open.
  5. From the main window of the GitHub Desktop application, click "Show in Explorer."

    Show_in_Explorer.png

  6. The File Explorer will open and display the folders in your repository. Navigate to your Testweb folder.
  7. Within the Testweb folder, delete all files except webpath.txt.

    Do not delete webpath.txt or your new pages will not work properly!
  8. Navigate to the folder containing the new default web pages you downloaded in step one. Copy the files within this folder into your Testweb folder.
  9. Return to the GitHub Desktop application. You should see a log of the changes made to the web pages in your directory.
  10. Enter a description of your changes (e.g., "Deleted old files and uploaded new 5.1 default web pages").
  11. Click "Commit to main."

    Commit_to_Main.png

  12. At the top of the application window, click "Push to origin."

    Push_origin.png

  13. Within a minute, your changes should be applied to your production server. View your Testweb and Production directories to verify that the changes were made appropriately and to check functionality.

    You may also need to do a hard refresh with CTRL-R if you find that your changes have not been applied.

Initiating Code Reviews (PCI Sites)

Note: The following information is only applicable to Atlas-hosted sites in the PCI environment (those that use a credit card payment gateway). Non-PCI sites will not have to undergo the code review process.

After making and testing changes in Testweb, you should then apply any changes you'd like to go live to patrons to the copy of your production pages contained in your forked repository. Once all changes are made, you can use the pull request feature in GitHub to submit the new version of your production pages for a secure code review by Atlas Staff. If approved, the changes will be made live to your patrons.

For guidance on ensuring your changes will pass the code review requirements, see Secure Code Review: Best Practices and Common Issues.

Creating a New Pull Request

VTL_VideoLink.png

To initiate a secure code review, you will have to submit a pull request to Atlas staff within the GitHub interface : 

  1. Navigate to your repository at GitHub.com, click the "Contribute" button, and select the "Open pull request" option.

    Contribute.png

  2. You will be taken to a new page where you can review all of the changes associated with the new pull request. Make sure that you have selected to merge the main branch of your forked repository with the main branch of the AtlasSystems-HS production repository, as shown in the image below:

    Merge_details.png

  3. Click Create pull request and a text entry box will appear on the page.
  4. Write in a title containing the name of your institution (e.g. "Aeon Web Page Changes for Atlas Systems University") and any details you'd like to include in the larger text box below the title, then click Create pull request again.

    Create_pull_request.png

  5. Your committed changes will now be sent to Atlas for review and you will be notified when the changes are made live. If there is an issue with any of the changes in your pull request, you will be contacted by Atlas staff who will work with you to resolve the problem(s).
Please only submit one pull request at a time. If you need to make additional changes to a previously submitted pull request before Atlas has completed the review, please make sure to close the original request using the instructions below before submitting a new one.

Closing a pull request

If you have submitted a pull request in error, or have decided you'd like to make additional changes to the web pages before going live, you can cancel your pull request to halt the code review process. Cancelling a pull request will not reverse any of your committed changes, it will simply remove the your request to have Atlas staff review those changes and make them live. After closing a pull request, you can then make any additional changes and submit a new pull request to Atlas for review.

  1. Go to the GitHub homepage (https://github.com/)
  2. Find your institution's AtlasSystems-HS production repository in the list in the lefthand sidebar and click to go to the repository's page.

    Repository_list.png

  3. Click on Pull Requests (1) at the top of the screen.

    View_pull_requests.png

  4. Click on the title of the pull request you want to close.

    Pull_request_title.png

  5. Enter a reason for closing the request, then click Close with comment.

    Close_with_comment.png

  6. Your pull request will be marked as closed. If closed in error, you can reopen the pull request from this same screen by clicking Reopen pull request

    Reopen_request.png

  7. If you need to make additional changes after closing a pull request, you should return to your forked respository, make the desired changes, and submit a new pull request following the previously detailed instructions in Creating a New Pull Request.

Version Control Systems

Since the web pages are now hosted in GitHub, if you are familiar with Git, feel free to use your favorite interface to edit your web pages. There are several free Git tools such as the aforementioned GitHub Desktop application or free editors that support Git like Visual Studio Code

Git tools will perform version control, meaning that all changes you make to your web pages will be tracked and can be rolled back to a previous version at any time. You will not need to create and maintain local backups of the files you are editing as Git will maintain a complete history of your changes essentially acting as a backup for you.

Questions?

If this article didn’t resolve your issue, please contact Atlas Support for assistance:

Contact Support