To make contributions to Standardhealthrecord.org, individuals can:
- Lodge any issues or comments you have on the issue page here. This will help the collaborative know about content you see missing from the site, weird styling bugs you notice, and ways the Standard Health Record can be improved.
- Fork the project on GitHub, make changes to your copy of the files, and issue a pull request to the main repository. Note: Never push changes directly to the repository without issuing a pull request. This step is key in allowing individuals to review changes prior to merging with any live versions of the website. For a detailed guide on doing this, see below.
Before getting started on any development, ensure the following are installed:
- Git, our version controlling tool.
- Ruby v2.3.3, the language that Bundler and Jekyll use. The specific version is needed for a gem used in Jekyll.
- Bundler, which can be installed with
gem install bundleronce Ruby is available for use.
- Jekyll, which can be installed with
gem install jekyll bundler.
- For Windows users, Cmder is a powerful command line emulator to serve as alternative to powershell. This has been helpful for some developers on the team.
Once the technology stack is downloaded, you can follow this command line guide or this desktop app guide on forking, cloning your fork, pushing changes back to your repository and lodging pull requests on GitHub.
In the local version of your repository, run the following command to get all of the appropriate Ruby Gems downloaded.
$ bundle install
Finally, delete the CNAME file from your fork of the repository. This file will be added back later when you are making a pull request, but should be removed until then.
Building the Project:
To run the project on localhost run:
bundle exec jekyll serve
To view the project on mobile browsers, you can serve the website up on your github project page by doing the following:
- Push all of your changes to your github repository.
- On the GitHub page for your fork, go to the settings tab and find the section for repository name.
- Change repository name from
your-account-name.github.io(yes, that means put your github account name there).
- Make sure that the changes you want to view are on the master branch.
- Open up the page
your-account-name.github.ioon the browser of your choice.
Testing the Project:
After making changes to the website, one should run a local instance of the project and walk through the following checklist to test the website before integrating into production:
- Make sure your browser has been hard-refreshed to reflect new changes.
- View on Google Chrome.
- View on Safari.
- View on IE.
- View on Firefox.
- View on Android.
- View on IOS.
- Go through this Section 508 Checklist to confirm compliance
- Check colors used for proper contrasting if they have been changed
- Perform accessibility testing using the WAVE chrome extension and Code Sniffer.
Pushing Your Project Changes:
- Run browser tests mentioned above on localhost.
- Push changes to your GitHub Fork of the repository.
- Run tests on mobile devices when
your-account-name.github.iohas been updated.
- Replace the CNAME file you deleted when you first pulled the repository; the file should be named CNAME and have in it
- If everything checks out, issue a pull request with the main repository.
- Wait for someone in the collaborative to review your changes, merge to master, and see your contributions go live!
- After your pull request has been merged, remove the CNAME file from your local repo again. Make sure to put this off until the changes have merged; pull requests continue to monitor changes you make even after you make the request.
NOTE: If http://standardhealthrecord.org returns
404 after merging in the request, ensure that the CNAME file has been added back!
Below you will find a comprehensive list of the technologies and tools the Collaborative's website is built with, along with a brief description and links to wher you can learn more:
- Ruby, the programming language needed for both bundle and jekyll to work, used to run bundler and manage all dependencies needed for the project.
- Bundler, a consistent environment for Ruby projects that tracks/installs needed gems, used to bundle together dependencies needed to run jekyll.
- Jekyll, a static site generator that pairs neatly with Github, used to generate our static site locally and remotely on github.
- SASS, a powerful style sheet language, extending CSS to allow for variables, nesting and parametrized styles, used for simplifying and modularizing our style sheets.
- Bootstrap Material Design, a material design inspired, bootstrap compatible styling library, used to style our HTML front end.
- FontAwesome, a library of scalable vector icons that can instantly be customized, responsible for the icons we use on the page.
About the Team Behind the Standard Health Record
The MITRE Corporation is a not-for-profit organization working in the public interest that operates federally funded research and development centers to provide innovative solutions to national problems.