search

philrosenberg / instrument-log

A place to log issues and work performed on instruments
1 stars 0 forks source link

readme

This is intended to be and "issues only" repo. That means there is no code here, we are just using the issues/bug tracking featres of GitHub because they are better than writing one ourselves. In particular, we are using the issues section to track problems with NCAS/AMOF community instrumentation - https://amof.ac.uk.

GitHub has a feature called "Issues", we are going to use this feature to log instrument work. In software these issues would often be bugs that people have found, but could also be feature requests. Here the "Issues" could be faults, but could also be deployments, calibrations, maintenance, etc.

Report a fault

If you are an AMOF user, you can REPORT A FAULT with AMOF instruments on this page by going through the following steps:

  1. Hit the issues tab at the top of the page
  2. Hit the new issue button on the right of the page
  3. Important - Under labels on the right hand side, select the instrument(s) affected
  4. Enter as much detail as you can about the issue you are having.
  5. Hit submit!
  6. You should automatically be "watching" the issue you create, so will get updates on notifications.
  7. Email the instrument scientist you are dealing with - they may not get a notification about the issue directly from here.

Logging work done on instruments

If you are an AMOF instrument scientist and you DO SOME WORK on an instrument, you can log it in the following manner

  1. Go to the issues tab at the top of this repo page.
  2. If an issue has already been created (e.g. someone has reported a problem on here) then select the issue in question. Otherwise create a new issue just like in the "report a fault" section above. Although Github calls these things issues, they can be any type of work - it could be a calibration, an upgrade a deployment or anything else you feel might need logging.
  3. Important - under "Labels" on the right, make sure you select the relevant instrument(s). This makes finding them easier.
  4. Under assignees on the right, assign the issue to yourself - this is optional, but it means if anyone else posts about this issue you will be notified.
  5. As the work progresses add comments to the issue. This means you don't need to record the work in one go. For example if you do a calibration, You could open an issue called "Calibrate FizzBuzz Instrument", with the description being "FizzBuzz instrument is out of calibration on 1st Jan 2025, so needs recalibrating before then". You can then post a comment saying you've done the calibration, noting any details you want. You could then post another comment with the results of the calibration.
  6. Add as much detail as you want. Some things that may be useful to add are companies who did work, contact details, part numbers, photos of the problem or the fix, documents you referred to. If some work you do contributes to another issue, you can reference it by typing # then type some words from that issue title - Github will show suggestions and link to that issue.
  7. If this has fixed the issue, then you can hit the Close issue or Close with comment button.
  8. If your work has closed multiple issues you can go to that issue and close it. Add a comment referencing back to your original post to save typing it all out again.
  9. IMPORTANT - it is way more imortant to put some information in immediately than put perfect information in never. If you don't have the part number then omit it and add a separate comment later. If you wait to put your resolution in until another day you will probably forget and then never do it at all.

Add new instruments to the log

If you are an AMOF instrument scientist you can ADD YOUR INSTRUMENTS in the following manner

  1. Go to the repository's Labels page. The direct link is https://github.com/philrosenberg/instrument-log/labels or you can get to it by hitting the Issues tab at the top of the page, then hit the Labels button next to the search bar.
  2. Hit the New Label button.
  3. Enter the name of your instrument as the label name. You can add a description if you want, but it isn't required.
  4. Hit Create Label!
  5. In the "Watch" dropdown in the top right, select how you wish to watch the repo. You probably want to select participating and @mentions.

View previous instrument work

You may want to VIEW PREVIOUS INSTRUMENT WORK or view all previous work done on an instrument. This is particularly useful if you have a problem and you want to see if similar problems have happened before. You can do this in the following manner.

  1. Go to the Issues tab.
  2. Enter a search term in the search box as needed and/or select the instrument you want to view on the Label dropdown.
  3. The issues shown will be open issues, i.e. incomplete work. If you want to view work that has been completed, then hit the "closed" button at the top of the list.