Contributing

Getting started contributing to the Wiki

So you want to add things to the wiki? Great! It’s relatively straightforward to contribute.

Here’s the TL;DR:

More details below.

1 Guidelines

[draft]

  1. Be Respectful: Treat all contributors with respect.

  2. Preserve Existing Content: Make an effort not to remove or overwrite content that others have written. If you believe clarification is necessary, e.g., if someone is incomplete in their description of a topic, prioritize adding information over removing what was already written. If changes are necessary, discuss them with the original author. If its not obvious, you can usually find out who contributed what by looking through the commit history.

  3. Strive for Clarity and Accuracy: Ensure that your contributions are clear, concise, and accurate.

  4. Follow Formatting Guidelines: Adhere to the formatting and style guidelines of the wiki.

  5. Cite & Link Out the Wazoo: When adding new information, make sure to link other pages and cite papers. Adding hyperlinks to other wiki pages will help others navigate the site. Try to be comprehensive in citing relevant papers, even if you don’t know the ins and outs of every one; the wiki can serve as a sort of “reference repository,” a place to start for future literature reviews.

2 How to Contribute

The wiki is managed through git/GitHub. If you’re new to git, you might want to check out this helpful video to get started; git can be intimidating, but its not too difficult to get the basics down.

To make edits, you’ll either need to be added as a member of the utcfc GitHub organization (reach out to TBD to get added), or you can fork the utcfc.github.io repository to make your edits. In either case, you will make edits on your local machine and push your changes back to the main repository. The below sections outline in more detail process for contributing, which is similar to the process for contributing to any open-source software package hosted on GitHub.

Important

As currently written this page assumes you are not a member of the github organization. If you are, the process is a bit simpler.

2.1 Fork the GitHub Repo

“Forking” a repository refers to copying the repository to your personal Github account, so that you can make direct edits. You can then request that these edits be merged into the main repository. To fork the repo, navigate to the utcfc.github.io Github repository. Click the “Fork” button at the top right to create a copy of the repository under your GitHub account. You should now have a repo yourname/utcfc.github.io.

You’ll then want to clone your forked repository to your local machine using the command:

git clone https://github.com/yourname/utcfc.github.io.git

replacing yourname with your GitHub username.

Then, navigate to the cloned repository directory:

cd utcfc.github.io

and create a new branch for your changes:

git checkout -b your-branch-name

where your-branch-name is just something descriptive to keep track of what this fork is for, i.e., yourname-edits.

2.2 Add yourself as an author

Your first edit should be to add yourself as an author of the wiki. Create a file authors/<yourname>.yml, containing the following

author:
- id: yourname
  name: Your Full Name
  email: your.name@gmail.com
  orcid: 0000-0000-0000-0000

There are many more fields you can enter, but its not necessary. Having each author listed in a separate file makes it easy to keep track of all contributors to the wiki, and list multiple authors for a given page.

2.3 Make your edits!

Now you can make edits to existing pages, or create new pages. All wiki entries are stored in the pages/ directory, and can be organized into subdirectories as needed. Be sure to follow the guidelines for contribution listed above.

Tip

Quarto provides a number of features to facilitate scientific/technical writing, including full LaTeX support, inclusion of tables/figures, and inline code blocks. Code blocks include automatic syntax highlighting for various languages, and can even be run inline to display the output directly in the document.

See Quaro’s markdown basics page for more info.

It can be helpful to see a live preview of the page as you’re writing. We recommend installing the quarto CLI (command-line interface) for this purpose. Once installed, from within the utcfc.github.io directory, the command

quarto preview

will render a live preview on your local machine. Note that you don’t need to run a full render locally, as this is done automatically when new updates are pushed to the remote repository.

If you’re editing in VS Code, the quarto extension can do the same thing, but integrated into your editor. It also provides markdown syntax highlighting/linting, shortcuts for running code inline, autocomplete of citation keys, and more.

2.4 Push your edits

Once you’ve made your edits, you’ll want to push them to the utcfc.github.io repository. To do so, you first need to commit and push your changes to your forked version of the repository:

git add .
git commit -m "Brief description of the changes made"
git push origin your-branch-name

Then, we need to merge your version of the utcfc.github.io repo into the main (live) version. This is done through a “pull request”.

  1. Navigate to the main utcfc.github.io repository.
  2. Click the “Compare & pull request” button that appears after pushing your changes.
  3. Fill out the pull request form with a title and brief description of your changes.
  4. Click “Create pull request” to submit your pull request.
Back to top