Contributing

Contributions are possible in many different ways, not all technical. How do I contribute? You can always contact us with questions.

Report a bug

Where to file an issue:

TaxonWorks the software - issue tracker here
TaxonWorks Docs (these pages) - issue tracker is here
TaxonWorks API - issue tracker is here

Before you file an issue:

Check to see that the issue is indeed new by carefully reviewing the existing issues.

While filing your issue:

Use a issue template if available, this categorizes your insights into more actionable items for those seeking to address it
Tell a story! Give us enough background so that we can replicate exactly what you did.
Include a success criterion. How do we know we've succeeded in addressing the issues without contacting you again?
Err on providing more, rather than less information.
Provide a meaningful title that identifies your role, and what you seek to accomplish, e.g. As an X I need Y to do Z
Provide links/URLs to the scenarios in question, particularly if referencing a specific data point
Consider adding Screenshots for context.

Code

See Code. For a slowly evolving experiment in sharing scripts based on TaxonWorks see also taxonworks_api_scripts.

First, thanks, this is complicated stuff. Interface (e.g. forms, reports, searches) mockups are graphical ways of asking for new features. We love to see them. To create a mock-up you can use tools like Illustrator, Photoshop, or more technical design tools like Balsamiq or Sketch, or just draw them on paper and take a picture with your phone. The issue templates have inputs for handling images, just drag and drop them there. Add a little story, or multiple pictures to help describe how you might use the interface.

Tips

Use the prefix Task - in the issue name to indicate the request for a new or improved task.

Provide a suggestion for a feature or improvement via a video

Send! It is super useful for you to record your screen, or position a video camera to capture your work on-screen and around you. This way we see exactly how you work. You can send us big videos through file sharing services like http://www.dropsend.com/. Find ways to Contact us here.

Documentation

This software and workflow together make it possible for all to contribute to TaxonWorks Doc. Note all the pages here in docs.taxonworks.org have an "edit this page" feature. Scroll down to bottom of this page to see it.

Editing

You can edit files offline, on your own local computer, or online within the browser.

You will need a Github account.

NOTE: Using this method also ensures everyone gets contribution credit and recognition along with the ability to generate metrics and track this work.

Online

A brief summary of the steps.

Login to your Github account.
Return to docs.taxonworks.org
On any given document, scroll to the bottom, and click Edit this page where you see a need.
Add or edit your text.
Ensure your edits follow the style conventions. We use Markdown to style text.
If you need to add an image see including a screenshot.
Click Commit changes to submit a "pull request."
In the form that pops up:
- Add a (very) brief description of your change in the field that has Update README.md in muted colors
- Add a longer optional description in the bigger box, if you want
- In your message do not use words like "Changed, tweaked, updated", describe what was done
- Choose the second option Create a new branch .... There is an exception to this, if your changes are small, and ready to go directly to the public site, then you can commit to the development branch.
Click Commit changes again

A TaxonWorks Docs GitHub repository team member will review, make edits, ping you with questions if needed, and then ultimately accept the pull request to "merge" this into our documentation.

What branch should I use?

In deciding which branch to make a change on start by asking the question: "Is my change ready to go live, right now?" If the answer is yes (and you have permissions) then you can commit to the development branch. If the answer is no (e.g. you want to further refine your text), then you should commit to a new branch.

In addition:

The development branch is the staging ground for the main branch.
You should always assume that development branch changes will go live at any time.
Development changes may accumulate before moving to main.
The main branch must never be committed to directly. Changes to main happen when development is merged into it.
It is always safest, and OK, to start a new branch.
It's best to limit the scope of your changes on each new branch.
If you have large/ongoing changes to your branch it's useful to start your editing session by merging development into your branch. This keeps the differences between development and your branch minimal.
If you are editing locally, make sure you syncronize your changes with those on the remote server (git pull) before you start your editing session.

Offline

Offline editing follows a typical Git-based workflow that are detailed on Github and many other places online.

Fork the repository
Clone the fork onto your local machine
Make a new feature branch
Edit, and commit to the branch
Push your local edits to your Github fork
Make a pull request

Including images

In adding documentation, you will note that on any page at docs.taxonworks.org you can click the Edit pencil icon to add / edit text. To manage the image files, for example screenshots, we add to the documentation, we use TaxonWorks Meta Project hosted on https://sfg.taxonworks.org. To add screenshots to this documentation, you'll need to become a member of that TaxonWorks Meta Project. Let us know you want to be added (e.g. send dlpaul AT illinois DOT edu an email, or ping us in Element or Slack). When taking screenshots, note the resolution of your computer's monitor makes a difference if these images are sharp and clear or out of focus.

Take the desired screenshots.
Upload these images (in bulk or one-at-a-time) to the TaxonWorks Meta Project using the New Image task.

In TaxonWorks, find the generated image link URLs, using the Filter Image task. Try Filter Image using the Housekeeping filter to limit your result set to only images uploaded by you.

In the resulting set, click on the desired image, then
Click the Navigate radial under the image and select Show.
From Attributes copy the short URL to orginal URL link.
Return to editing documentation and use the Markdown format or HTML format below to insert image URLs (examples next).
- Note that both methods allow you to specify the image size.

Image caption markdown (writing docs)

Examples here show the markdown (md) format for adding a caption to an image.

Select one of the four options below for your caption. Put that text string into the documentation as described next.
With the position option, choose left, center, or right which aligns your caption text according to what you pick.
Enter the text of your choice in-between the brackets [caption text goes here].
Paste in the short URL to orginal URL link (from Filter Image > Navigate radial > Show > Attributes).
Add alt text in-between brackets. It is best practice to include this for accessibility.
(Optional) Declare the width or height or both of the image to control the size displayed.
- The default sizes works well. Sometimes, depending on the screenshot, it might appear too large and then this option gives you the ability to modify the size.

#position[caption text goes here](link [alt text if you want it])
#position[caption text goes here](link [alt text if you want it] w{60%})
#position[caption text goes here](link [alt text if you want it] h{50%})
#position[caption text goes here](link [alt text if you want it] w{80%} h{50%})

HTML for image with caption

<figure>
  <img
    src="https://sfg.taxonworks.org/s/rdc03q"
    alt="Sample image"
    style="width:100%"
  />
  <figcaption>Fig.1 - A TaxonWorks Interface</figcaption>
</figure>

Adding a file

After you fork the repository you can use Github directly to add a new file . You can also add a new file within the Github interface

Ordering sidebar content

In brief this is controlled alphabetically, or it can be over-written via 2 frontmatter parameters, sidebarPosition and sidebarParentPosition.

sidebarPosition

Where: In any (README.md or other) documentation file. When: You want to position the content of that document within the context of the other files within that directory.

sidebarParentPosition

Where: Only in a README.md. When: You want to position the name of the directory within the context of other directories and files at the level of that directory.

Order by filename

First, the system will take the files within the directory in alphabetical order of the filenames to generate the sidebar. For example:

Folder structure:

-- My folder example
---- bar.md
---- foo.md

Filename: foo.md

# A is the first letter of this title

Filename: bar.md

# B is the first letter of this title

My folder example
  B is the first letter of this title
  A is the first letter of this title

Order by sidebarPosition variable

sidebarPosition allows you to change the order of the sidebar regardless of the alphabetical order of the files. Let's take the example above, but now we're going to add sidebarPosition in each file to change the order: