{"id":22217662,"url":"https://github.com/fredhutch/wiki","last_synced_at":"2025-04-11T10:56:21.307Z","repository":{"id":38984168,"uuid":"130756701","full_name":"FredHutch/wiki","owner":"FredHutch","description":"SciWiki: Collective KnowledgeBase for Scientific Data and Use","archived":false,"fork":false,"pushed_at":"2024-05-22T17:31:07.000Z","size":37815,"stargazers_count":32,"open_issues_count":57,"forks_count":41,"subscribers_count":86,"default_branch":"main","last_synced_at":"2024-05-22T18:42:52.664Z","etag":null,"topics":["bioinformatics","community","computing","data-science","documentation","fhdasl","open-science","sciwiki","wiki"],"latest_commit_sha":null,"homepage":"https://sciwiki.fredhutch.org","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FredHutch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-23T21:05:12.000Z","updated_at":"2024-05-29T06:30:57.990Z","dependencies_parsed_at":"2023-10-14T16:14:42.534Z","dependency_job_id":"9bd88bc3-db6a-49bd-a6db-3ad1aba2a94b","html_url":"https://github.com/FredHutch/wiki","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FredHutch%2Fwiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FredHutch%2Fwiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FredHutch%2Fwiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FredHutch%2Fwiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FredHutch","download_url":"https://codeload.github.com/FredHutch/wiki/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381366,"owners_count":21094482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","community","computing","data-science","documentation","fhdasl","open-science","sciwiki","wiki"],"created_at":"2024-12-02T22:17:16.558Z","updated_at":"2025-04-11T10:56:21.290Z","avatar_url":"https://github.com/FredHutch.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contributing to SciWiki\n\nThis curated Wiki relies upon the Fred Hutch research community itself to improve, expand and evolve over time.  Because the Wiki's content spans many research areas, we need and welcome contributions from a similarly wide range of researchers and Fred Hutch staff.  Whether this contribution is as novice reviewers for a topic outside of their expertise or as expert contributors for those topics of most interest to them, no contribution is too little (or too large).\n\nTo contribute to the Wiki you only need to have your GitHub username added to the Fred Hutch Github Institution (and the AllFredHutchTeam).  Email `scicomp` and provide your GitHub username and request to be added.  If you are interested in being part of the Wiki Reviewers Team (see below for their role), please email `apaguiri` and Amy will add you to the GitHub team for that.  \n\n# Outline of this document:\n[Content Contribution and Review Process](#content-contribution-and-review-process)\n\n[Contributing via an external editor](#contributing-via-an-external-editor)\n\n[Wiki content style guide](#wiki-content-style-guide)\n\n[Repository structure](#repo-structure)\n\n[Viewing rendered changes to non-`main` branches](#viewing-test-builds)\n\n[Building a copy of this Wiki locally](#building-the-site-locally)\n\n[Building a copy of this Wiki on a rhino](#building-the-site-on-rhino)\n\n[For Admins](#for-admins)\n\n\n## Content Contribution and Review Process\n\n### Content Types\nWe manage the content of this site via a set of markdown files that contain long, article-style text (our main pages in the site) and a handful of focused cookbook/demo-style documents (Resource Libraries).\n\nArticles use an outline structure to allow graduated content, starting from basic information and progressing to more detailed content for expert users/readers. Using headers (H2 through H4) in the text allows the automatically rendered Table of Contents to facilitate readers' ability to jump around the documents to get to needed content as well as the creation of anchors to allow for linking directly to portions of content in a longer page.  By keeping related text together in a small number of pages, it allows us to provide more context for people who are learning about a topic, allows finding of other related information a reader might not have known to look for, AND allows content providers to manage content in ONE PLACE rather than spread throughout the site.  \n\n\u003e Note: This site is created by researchers and staff who are not web designers nor technical writers by training!  Thus, we have opted for a relatively flat organizational structure to keep it simpler for content curators and to reduce the risk of information becoming stale and irrelevant as much as possible.  \n\nThe more focused, how-to style, Resource Library entries in both the Data Generation and Scientific Computing domains can use headers as well to populate a Table of Contents for each of these pages.  These documents are intended to be fairly detailed examples or content that is linked to by Articles, but address a specific use case or example scenario that may be only intended for advanced users/readers.  Once a number of related Resource library entries are created, Editors may consider consolidating the information and moving it into the main site as a full Article to highlight the content to new readers.  \n\nBoth Articles and Resource Library entries are full-text searchable using the search feature (the magnifying glass in the header).  This search ability is the primary strength behind this Wiki and will be the primary way people will find content, as, again, no web designers or technical writers are involved in this grassroots project.  \n\n**NEW (as of March 2022)** - Introducing **Pathways**!  Pathways are a new approach we are incorporating which can be found by following the [Pathways link](https://sciwiki.fredhutch.org/pathways/) in the sidebar from any domain.  This Pathways page will host individual pages that provide users who want to do a commonly requested set of tasks, a list of pages/links in the order they'll want to read them, that will guide them along the pathway to doing what they want.  We hope this might be an alternate mode for finding content in the Wiki that the community finds useful.  If you have ideas for new Pathways, please [file an issue](https://github.com/FredHutch/wiki/issues) and tell us about it.  \n\n### Adding/Editing Content\n\n#### Methods to Edit\nThere are multiple ways to edit content on our site, including:\n\nFor spot checks, small edits/refinements or those of us not familiar with git or GitHub:\n- Clicking on the \"Edit this Page\" icon on any page, providing your edits, committing them to a branch and doing a pull request (GitHub will guide you in this process).\n\nFor larger edits, multi-page edits, structural changes or expert users of git/GitHub:\n- Cloning the Wiki repository to your local machine, committing edits to a new branch, pushing those edits to GitHub and doing a pull request (requires knowledge of git and GitHub workflows).\n\n#### General Editing Process\nTo edit one of the content-containing markdowns (see below regarding Repo structure for more info about where these markdowns are) from GitHub, follow these steps:\n\n1. Create a branch off the main branch for your edits. Do *not* fork the repo or others cannot submit additional edits to your content.  Consider naming the branch in such a way that indicates what domain the edits will primarily be in (such as \"generation-typos\" or \"intro-to-rhino\").  Avoid making branches with names that don't attempt to describe the types of changes made whenever possible. For your content to be merged into the main branch, it will likely need to be edited by others, and it is possible that others may have substantial content to add to your edits.  If the branches are named according to content being added (generally) then others can contribute to that content too.  \n2. Commit your edits to existing markdowns as you go, and update from the main branch before continuing to work on your branch.  You will reduce future conflicts if you get in the habit of updating from the main branch and committing frequently.  \n3. Publish/push your branch to GitHub to share your edits with the group.\n4. When you are done editing, create a pull request from your branch. This pull request step highlights your branch for consideration by potential contributors and editors! Suggest reviewers based on the content of the edits if you'd like by tagging their GitHub usernames (using @...).  Request admin assistance if your content may be new and need to be hooked up to the sidebar or other web-specific needs (this is currently done by tagging `vortexing` or `bmcgough` for a review).  \n\n    \u003eNote: If you are editing existing content and the page has a listing for the Primary Reviewers like this:  `primary_reviewers: somegithubusername` then when you submit the pull request please request a review from those usernames.  \n\n5. Reviewers will sign off on edits by approving or providing comments on a pull request, ideally one \"expert\" and one \"novice\" based on field of expertise.  If there is a `primary_reviewers` listed for content then one of the reviews must be from one of those members.  Others may move your content to combine it with other work, or make edits that you may want to review as well.  Keep an eye on your pull requests and comments on it in order to check back in if someone's edits need your review as well.  \n6. Once approving reviews have been obtained, the pull request can be merged into the main branch and then any edits go live to the site [here.](/)\n\n### The Review Process\n\n#### Who can contribute content?\nThis Wiki is intended to be curated by content owners, local experts, and service providers at Fred Hutch in order to ensure accuracy and relevancy to our community.  Anyone can file Issues with suggestions and requests at any time.  Direct contributions and reviews can only be made by users who have GitHub usernames affiliated with the Fred Hutch GitHub institution. Individuals from other institutions who are working with the Hutch community are encouraged to file an issue to discuss collaboration with the current project leaders.\n\n\n#### How is content reviewed?\nChanges to the Wiki are assessed via [pull requests to this GitHub repository](https://github.com/fredhutch/wiki/pulls). We use the `primary_reviewers` tag in our markdowns to indicate when there is a resident expert who should be contacted via pull request review requests when content in that markdown is edited. This process of contribution and review from multiple different users allows us to make sure that the content evolves in such a way that it it both more interpretable to the intended audience (Fred Hutch affiliated staff), but also accurate, appropriate and continuously reviewed.\n\nWhen a pull request is made, it automatically requests a pull request review from any member of the [Wiki Reviewer Team](https://github.com/orgs/FredHutch/teams/wiki-reviewers). While reviews from other experts is welcomed, a review from a Wiki Reviewer Team member approving the changes is *required* prior to merging the pull request (this is enforced by [protection of the main branch](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews#required-reviews)). In addition to regular communication among the Wiki Reviewer Team, we work with the the Hutch's Information Security Office to ensure published content maintains agreed upon standards for information security.\n\n### Getting Credit\nPlease remember to make a [markdown for yourself](https://github.com/FredHutch/wiki/blob/main/contributorTemplate.md) in our `_contributors` directory so that we can give you credit for your contributions publicly on the site if you would like to.  \n\n## Contributing via an external text editor\nYou can also contribute to the wiki from external editors that can interoperate with GitHub. We have had good experience with [Atom](https://github.atom.io/) but other text editors have GitHub integration as well.  Also there is a tutorial on how to use [VSCode](/compdemos/vscode_markdown_howto/) which is what you will want to use if you plan to contribute many screenshots or other images.  \n\n## Wiki Content Style Guide\n### Github-Flavored Markdown\nThe content of this site is generated using GitHub \"flavored\" markdown.  A cheat sheet for the code required to create things like headings and table is [here.](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) Our page TOC's are generated from these headings, so use ## H2 as your first level, and headings H2, H3 and H4 show up automatically in our TOC's.\n\n### Inserting Links\n\nIf you would like to insert a link to another page in our site, please use:  \n```\n[text you want to have highlighted](/domain/markdownfile_name/)\n```\n\nIf it is a link to an external site use:  \n```\n[text you want to have highlighted](https://my.url.com)\n```\n\n\n### In-text Images\nIf you'd like to add images to your entry, some text editors (eg. Atom or VSCode via their respective plugins) allow for copy-and-pasting of images.  You can read some instructions on how to get set up with VSCode in one of the Computing Demo's.  \n\nOne edit is that in order for Jekyll to correctly render the images in a page, they should be placed in the `assets` subdirectory of the directory containing the page being edited. The following text is the example format that the call to the image needs to be in for a markdown in the **_compdemos** folder:\n```\n![](/compdemos/assets/2018-06-13-16-47-59.png)\n```\nIf the markdown you are editing is in one of the other folders you'll need to change the `compdemos` string to whatever the text of your folder is; please leave out the underscore at the beginning of the folder name.  \n\nBoth Atom and VSCode will make a directory called `assets` in the directory where the markdown is, and then will copy your in-text image file there so you can commit it all to the repo.  \n\n#### Custom sized images\nIf you want to adjust the size of your image, you can add your image using HTML syntax. Be sure to include the `alt` attribute.\n\n```\n\u003cimg src=\"/compdemos/assets/2018-06-01-12-34-51.png\" alt=\"VS Code extensions tab\" width=\"500\" height=\"600\"\u003e\n```\n\n### External Videos and Images\n\n#### Images\n\nBefore linking to external images, consider saving a copy and creating an internal link as outlined [here](#in-text-images). This helps ensure content doesn't break over time.\n\n#### Youtube\n\nWhen linking to videos like screencasts you typically want to show an image screenshot and clicking on that screenshot starts the video. Images of videos are stored at https://img.youtube.com/vi and they use the same video id you find in Youtube URLs, so The Gift of Time is `https://youtu.be/rN7cmb1K2yA`. To embed, insert this into markdown:\n\n    [![The Gift of Time](https://img.youtube.com/vi/rN7cmb1K2yA/0.jpg)](https://youtu.be/rN7cmb1K2yA \"Click to see The Gift of Time\")\n\nIt is also important to consider the following parameters for videos from outside sources:\n* `rel=0` - this restricts the related videos shown at the end of payback to videos from the same channel rather than account-based recommendations\n* `iv_load-policy` - set to *1* to display video annotations by default and *3* to disable annotations\n\nSo the above link modified would be:\n\n    [![The Gift of Time](https://img.youtube.com/vi/rN7cmb1K2yA/0.jpg)](https://youtu.be/rN7cmb1K2yA?rel=0\u0026iv_load_policy=3 \"Click to see the amazing kitten\")\n\nIf you need to make screencasts, free software exist for [Windows](https://www.apowersoft.com/free-online-screen-recorder), [Linux](https://launchpad.net/kazam), and [OSX](https://www.webascender.com/blog/free-screencast-software-built-right-mac-os-x/).\n\n### Referencing a Fred Hutch username\nPlease if you need to reference a Fred Hutch username, do not write the entire email address out, just put the username in backticks like this:\n\n```\n`username`\n```\n\n## Repo structure\nThe general contributor should likely have no reason/need to edit any of the files in the main directory of the repository, nor files in any other subfolders besides the ones described below.  The folders below contain the content portions of the site, while the other folders and files contain all the necessary information to actually BUILD the website itself.  \n\n### Content-Housing Folders\n\nData Science Content is here: https://github.com/FredHutch/wiki/tree/main/_datascience\n\nScientific Computing Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/main/_scicomputing\n\nComputing Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/main/_compdemos\n\nContributors List (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/main/_contributors\n\nFor new contributor entries: https://github.com/FredHutch/wiki/blob/main/contributorTemplate.md\n\nPathways page (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/main/_pathways\n\n\n\n## Automated deployment\n\nEverything merged into the `main` branch will be automatically deployed to [https://sciwiki.fredhutch.org/](https://sciwiki.fredhutch.org)\n\nEverything in any *other* branch pushed to GitHub will be deployed to [https://sciwiki-preview.fredhutch.org/](https://sciwiki-preview.fredhutch.org) ,\nwhich is only accessible inside the Fred Hutch network.\nThis will always reflect the last (non-`main`) commit/push to the repository.\nYou can check what branch and what commit is reflected by going to \n[https://sciwiki-preview.fredhutch.org/info.txt](https://sciwiki-preview.fredhutch.org/info.txt).\n\n\n\n## Viewing Test Builds\n\nThere are two ways to view changes to the wiki (that have not been pushed to the `main` branch) without building the site yourself (for that, see the next section).\n\nThe first way is to view the [preview site](#automated-deployment). This has some limitations, as described in that link.\n\nThe other way is to download a build artifact, which is a zip file containing the static, rendered pages of the site.\n\nThese artifacts are only produced when there is a *successful* build of the site on any branch.\n\nYou can access the build artifacts [here](https://wiki-artifact-app.fredhutch.org/) (within the Fred Hutch network only).\nThis will show recent builds of the CI/CD pipeline, starting with the most recent. It gives information about the commit and who created it. You can download the associated build artifact by clickng \"Download static files\". This will download a file called `artifact.zip` to your local machine.\n\nUnzip the file. You will see that it contains an `html` directory at the top level.\n\nIn order to view the site properly, you must use a web server. if you just try to open the `index.html` file inside the `html` directory in your browser, the site will not render properly.\n\nOne easy way to serve the site with a web server is to use Python. If you are in the directory where you downloaded and unzipped `artifact.zip`, you can just run this command:\n\n```bash\npython3 -m http.server -d html\n```\n\nThat will make the site available at the URL `http://localhost:8000`.\n\nNote that build artifacts expire after 2 weeks, at which point they can't be downloaded.\n\n## Building the site locally\n\nYou may want to build a copy of this wiki locally (on your own computer) to make sure that it looks the way you want before pushing your changes.\n\n### Steps\n\n1. clone the repo somewhere\n1. `cd` to the directory where the repo is cloned\n\nAt this point there are two different methods you can use to build the site.\n\n#### Method 1: Docker\n\nIf you have Docker installed, run:\n\n```\n./docker-build.sh\n```\n\n#### Method 2: Local build without Docker\n\n1. Install Ruby (version 1.9.2 or later).\n**Note**: most modern Mac computers already have Ruby installed. If you still need Ruby,\nit can be found [here](https://www.ruby-lang.org/en/downloads/).\n1. On Mac, install xcode commandline tools `xcode-select --install`\n1. You may need to install `bundler`. Type\n   `which bundler` to see if it is already\n   installed. If nothing is returned, then\n   install `bundler` with `gem install bundler`.\n   If that fails, try `sudo gem install bundler`.\n1. You may need to install gems used by the site.\n   Type `gem install -g Gemfile` to install all of the gems the site uses.\n   - If you get an error `mkmf.rb can't find the headers for ruby at /some/path/to/ruby.h` or something very similar, you need to install the `ruby-dev` package.\n   - If you get an error that `zlib is missing` you need to install the `zlib1g-dev` package.\n\n\nNow run\n\n```\n./build.sh\n```\n\n#### View the built site\n\nWith both methods, you should be able to see the\nbuilt site (once the build is done) by going to\n[http://localhost:7979](http://localhost:7979) in your browser.\n\n\n## Checking for broken links\nTo check for broken links, you can type\n`rake test`. This will exit with an error if there\nare any broken links, and list the broken\nlinks and the files they are found in.\n\nIf you are inside the Fred Hutch network, you can type\n`rake testlocal` and that will include internal URLs\nin the check.\n\n## Building the site on rhino\n\nFirst, clone the repo on a rhino and check out the branch or commit you want to look at,.\n\n### Load a current Ruby version:\n\n```\nml Ruby/3.0.1-GCCcore-11.2.0\n```\n\n### Install gems\n\n```\nbundle install\n```\n\n### Build\n\n```\nbundle exec jekyll build\n```\n\n### Serve\n\n```\nbundle exec jekyll serve -H 0.0.0.0 -P \u003cport\u003e\n```\n\nSelect an unused port over 1024.\n\n### View\n\nPoint your browser at your current hostname on the port you specified in the `serve` command above (example: `rhino01:5678`).  Once this has started, the site will be rebuilt when updates are made to any of the source files in the site.\n\n## Glossary terms\n\nThe site contains functionality allowing \ncontent authors to define words such that a tooltip with the definition (and optional URL) appears when the mouse hovers over the word(s).\n\nYou can set this up using the following formatting:\n\n```\n{% glossary Foo %} is one of my favorite words.\n```\n\nThen in the file `_data/glossary.yml` you can add a definition like this:\n\n```yaml\n- term: Foo\n  definition: A nerd term meaning anything really.\n  url: https://en.wikipedia.org/wiki/Foobar\n\n```\n\nNote that the `url` is optional. Is there is no relevant URL you can leave it out.\n\nThis functionality is possible by using the [jekyll-glossary_tooltip](https://github.com/erikw/jekyll-glossary_tooltip) plugin (see [demo](https://erikw.github.io/jekyll-glossary_tooltip/)). \n\nNote that this plugin is *not* one of the plugins approved by GitHub to be used with GitHub Pages, so this site is no longer hosted by Pages. Instead we build it ourselves using our CI/CD pipeline.\n\n## For Admins (everyone else, please do not edit these as your edits will be ignored/removed)\n\n### Pages that run Demo and Contributors Collection pages:\nData Science resource library collection page:  \nhttps://github.com/FredHutch/wiki/blob/main/datademos.md\n\nComputing resource library collection page:  \nhttps://github.com/FredHutch/wiki/blob/main/computingdemos.md\n\nSciComp Announcement resource library collection page:  \nhttps://github.com/FredHutch/wiki/blob/main/scicompannounce.md\n\nContributors list collection page: \nhttps://github.com/FredHutch/wiki/blob/main/contributorslist.md\n\nPathways collection page:  \nhttps://github.com/FredHutch/wiki/blob/main/pathways.md\n\n### Folders containing website configuration files\nMain website configuration file: \nhttps://github.com/FredHutch/wiki/blob/main/_config.yml\n\nNavigation yml:\nhttps://github.com/FredHutch/wiki/blob/main/_data.yml\n\nCustom styling that overrides the remote theme:\nhttps://github.com/FredHutch/wiki/blob/main/assets/css\n\nHeader and footer configs:\nhttps://github.com/FredHutch/wiki/blob/main/_includes\n\nGlossary yml:\nhttps://github.com/FredHutch/wiki/blob/main/_data/glossary.yml\n\n### Other pages:\nOur index page: https://github.com/FredHutch/wiki/blob/main/index.md\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffredhutch%2Fwiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffredhutch%2Fwiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffredhutch%2Fwiki/lists"}