Editing Atlas-Hosted Aeon Web Pages in GitHub

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 

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)

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 repositories in GitHub:

1. A production repository (AtlasSystems-Prod) 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. 

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.

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

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: 

Downloading a Backup of Your Web Pages 

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. 

   

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.

Making Changes

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. PCI sites must ensure that all desired changes to production web pages are on the main branch of the AtlasSystems forked repository before a pull request to Atlas is created for a secure code review.

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. 

   

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.

   If you do not see this option or if you see a message stating that you do not have write access, check to make sure you attempting to edit a file in your AtlasSystems forked repository. If you still do not see this option, please contact support@atlas-sys.com. 

   

   Do not select the Create a new branch for this commit and start a pull request option as any edits made outside of the main branch of your forked repository will not be synced to your production repository. If you would like to create a pull request after making a change, please commit your changes using the Commit directly to the main branch option then follow the steps for creating pull requests outlined in the Creating a New Pull Request section.

View Change History 

To see all the changes for a specific webpage:

1. Navigate to the appropriate web page.

2. Click the History button.

   

3. Click the title of the change.

   

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.

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

Reverting Changes

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.

   

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.

   

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. 

   

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.

   

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.

   

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

Using Testweb

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 

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.

   

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."

   

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, web.config (if present), and any files ending in .dll (if present).

   Do not delete these files 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."

    

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

    

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)

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.

Creating a New Pull Request

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.

   

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-Prod production repository, as shown in the image below:

   Any pull requests submitted to Atlas coming from a branch other than main will not be approved.

   

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.

   

5. Your committed changes will now be sent to Atlas and scanned for an initial automated review. The review process will be initiated and completed within a minute, with results posted on the pull request page (no refresh is required):

   Note: The automated code review process is currently in beta testing and is not yet available for all sites. Those without this feature will have code reviews completed manually by Atlas staff following the normal procedure.

   • If issues are found, you will see either an All checks have passed, 1 neutral check or All checks have failed message as well as an automated code review report listing the number of issues found categorized by severity:

     

   • If no issues were found, you will see All checks have passed, 1 successful check, and can skip to step 11:

     

   For more details on the automated code review scan outcomes and report, see Atlas Automated Code Review Service.
6. If issues were found, review the posted results on the pull request page and note any critical issues that must be immediately resolved. Review the associated code review report and determine if any non-critical issues should be resolved before your changes go live.
7. Close the pull request if it is determined that any of the flagged issues must be resolved before your changes are made live to patrons.
8. Return to your forked repository and use the automated code review report to locate each issue, then follow the guidance in the Resolving Issues in the Automated Code Review Report article to edit the file(s) and resolve the issue(s).
9. Once all issues are resolved, submit a new pull request. The automated code review bot will run another scan.
10. Review the results of the new scan and determine if all immediate issues have been resolved:
    • If immediate issues remain, repeat steps 7-9 until no immediate issues are found.
    • If any code has been flagged for manual review, Atlas staff will perform a review of the associated code and contact you if issues are found.
11. If no issues are found or all critical issues have been resolved, Atlas staff will perform a final review and you will be notified when the changes are made live. 

Closing a pull request

If you have submitted a pull request in error, have decided you'd like to make additional changes to the web pages before going live, or need to resolve issues flagged by the code review, 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 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-Prod production repository in the list in the lefthand sidebar and click to go to the repository's page.

   

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

   

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

   

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

   

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. 

   

7. If you need to make additional changes after closing a pull request, you should return to your forked repository, 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.