Welcome!
If you have experience with and are comfortable using Git and GitHub, skip this file and read through A quick workflow for experienced Git, GitHub, and Asciidoc users to learn how to contribute to the WGFAST convention documents.
The rest of you, do not panic!
Please keep reading. 😄
We realize that learning Git workflows and commands is probably not what you thought of when you thought of contributing to the WGFAST conventions. Don’t worry. We have created several help files to get you up and running with the least amount of friction. You concentrate on contributing to the WGFAST conventions and we will take care of the "Git-stuff".
You might be thinking that using a Git workflow to edit the WGFAST conventions is overkill. The conventions are text documents, not software. Yes, Git is widely used in tech industries to track source code changes and develop software, and it has a lot of terminology that can be confusing if you are not familiar with it. But at its core, Git is an open-source and well developed distributed version control system - it tracks all changes in a project from multiple contributors. That is why we are using it.
-
You cannot delete, erase, destroy, implode, explode, or generally mess up the master documents. They are safe in the
ices-eg/wg_WGFAST
repository behind permissions you cannot change. -
Do not be afraid to make mistakes in your repository. When you start learning Git, have fun with it - it is your repository to experiment with. We all blew up a few repos starting out. If you make a mistake that you cannot come back from, you can delete your repository and fork
ices-eg/wg_WGFAST
again. -
Your terminal will not bite you. Unless you somehow get into your system’s operating files (do not go there!), you cannot do too much damage at the command line.
-
If you do not want to work in a terminal you can use either the Atom or Brackets text editors/IDEs. Both have Git/GitHub integration and you can use a GUI for most Git commands.
-
Read the rest of this page. This is a README file. Most folders in the
ices-eg/wg_WFAST
repository has an associated README file with information about the other files in that folder. -
Read through the Suggested setup to contribute to the ICES WGFAST convention documents.
-
Read through the Git and GitHub terminology file. There also a graphic of the workflow in that file.
-
Read through the Suggested workflow to contribute to the ICES WGFAST convention documents.
-
Read the individual help files when needed.
Links to all the help files are at the bottom of this document, or you can click on a document’s link at the top of this page.
What is a Git repository? A repository is a permanent record of a project’s development.
wg_WGFAST
is a repository managed by ices-eg
folks on GitHub.
ices-eg
is the ICES Expert Groups' GitHub account. It is an account of "Workspaces for ICES expert groups to archive code and case-specific methods". wg_WGFAST
is the repository for the working group on Fisheries Acoustics, Science and Technology.
-
How_to_contribute
: Contains help files on how to contribute to the conventions. You are in this folder. -
AcMeta
- Contains the A metadata convention for processed acoustic data from active acoustic systems document and supporting files. -
SONAR-netCDR
- Contains thedocs
subfolder with the The SONAR-netCDF4 convention for sonar data, Version 1.1 document and supporting files, and thesrc
subfolder with MATLAB code. -
SISP_formatted
- Contains the latest HTML file of the metadata convention. You can view this file in your web browser by going here. -
.github/workflows
- Contains the.yml
for a GitHub Action to build the HTML and put it inSISP_formatted
. Do not touch this file, please.
If you still have questions about how to contribute to the convention documents after reading through the help files in the "How to contribute" folder, please open an issue in the issue tracker and submit your questions there. Mention @erinann
in the issue.
If you do not know what Git commits are, or if you think "forking a repository" refers to dueling with cutlery, do not worry. We will not make you a Git or GitHub expert, but we will get you sorted enough to know how to stage commits, push those commits to your remote repository, pull updates from an upstream repository, and submit pull requests in order to contribute to the convention documents.
If you do not know what a markup language is (specifically AsciiDoc markup) or how to preview markup documents, do not worry. Again, we will not make you an expert in these things, but we will get you editing with as little pain as possible.
🔥
|
Setting up live preview of AsciiDoc markup documents with a browser extension was not easy. Compiling the documents (also called "creating backends" (HTML, PDF, DocBook, etc.) on a computer was even harder. Unless you know Ruby and RVM and are deeply familiar with your operating system, do not try these things. |
💡
|
In lieu of installing browser extensions, the Asciidoctor toolchain, and all the dependencies, we recommend using a text editor/IDE that can edit and provide live previews of AsciiDoc documents. AsciidocFX, Atom, or Brackets are three suggested text editors/IDEs. |
AsciidocFX, Atom, and Brackets are text editors/IDEs that can read, edit, and live preview AsciiDoc documents. All three editors can interact with GitHub through a terminal or a terminal emulator or a GUI.
ℹ️
|
Previews of citations in AsciiDoc documents do not currently work in Atom or Brackets. Previews of math equation (LaTex math) in AsciiDoc documents does not currently work in Atom, but you can change the settings of the AsciiDoc preview pane in Brackets to preview math equations. |
ℹ️
|
The help files are written in AsciiDoc (.adoc) markup. If you want to take a quick peek, click on the Raw button above. If you installed an AsciiDoc browser extension, make sure you turn it off to view the markup.
|
Filename | Document name |
---|---|
1_suggested_setup.adoc |
Suggested setup to contribute to the ICES WGFAST conventions |
2_suggested_workflow.adoc |
Suggested workflow to contribute to the ICES WGFAST conventions |
3_github_help.adoc |
GitHub help |
4_git_help.adoc |
Git help |
5_plain_text_editor_help.adoc |
Text editors/IDEs help |
6_asciidoc_help.adoc |
AsciiDoc help |
Git_and_GitHub_terminology.adoc |
Git and GitHub terminology |
Atom_Git_GUI.adoc |
How to use Git/GitHub GUI in Atom |
Brackets_Git_GUI.adoc |
How to use Git/GitHub GUI in Brackets |
experienced_github_users.adoc |
A quick workflow for experienced Git, GitHub, and Asciidoc users |
README.adoc |
How to contribute to the AcMeta and SONAR-netCDF4 documents |