Skip to content

Latest commit

 

History

History
55 lines (42 loc) · 3.3 KB

1_suggested_setup.adoc

File metadata and controls

55 lines (42 loc) · 3.3 KB

Suggested setup to contribute to the ICES WGFAST conventions

These instructions are for contributors who have not used Git, GitHub, or AsciiDoc markup get started.

If you have experience in Git and GitHub, skip the setup and workflow files and read through A quick workflow for experienced Git and GitHub users.

Table of Contents

What have I gotten myself into?

There is a lot of jargon surrounding Git and GitHub, but that is normal in any specialized field. Try explaining what you do to a five year old without using the terms, "backscatter", "decibel", and "transducer". Thankfully, you do not need to be an expert in multiple programming languages or fields of computer science to contribute to the WGFAST convention documents. You only need to be the fisheries acoustic expert that you are and to understand a few core concepts of Git and GitHub. These documents are here to help you with the latter.

Software, accounts, and languages

Software to install

Git - A distributed version control system.
AsciidocFX or Atom or Brackets - Modern text editors/Integrated Development Environments (IDEs). AsciidocFX, Atom, and Brackets can open, edit, and live preview AsciiDoc files.

If you prefer to work online (in GitHub), you will not need a text editor. However, we suggest using a text editor if you are going to do more than fix a few spelling errors.

Account to create

GitHub - A cloud-based hosting service used to manage Git repositories.

Markup languages to learn (only a little)

AsciiDoc - extension .adoc
AsciiDoc is a popular and flexible plain text markup language. Both convention documents are written in (or being converted to) AsciiDoc markup. GitHub automatically renders .adoc files into HTML. If you are reading this file on GitHub, you are reading the HTML render of an AsciiDoc file.

Markdown - extension .md
Markdown is the most popular plain text markup language but it is not as flexible as AsciiDoc. You will see a couple documents in the wg_WGFAST repository with .md extensions (eg - README.md). These are written in Markdown. GitHub automatically renders Markdown files into HTML.

AsciidocFX, Atom, and Brackets can open, edit, and live preview AsciiDoc and Markdown files.

Suggested order of setup

If you do not have any of the software or accounts listed in the section above, this is the most painless way to get started.

  1. Create a GitHub account. See the GitHub Help file.

  2. Install Git. See the Git Help file.

  3. Install AsciidocFX or Atom or Brackets and the necessary packages or extensions to read .adoc and .md files. See Text editors/IDEs help file.

  4. Learn a little about AsciiDoc markup. See the AsciiDoc Help file.