Difference between revisions of "Getting Help"

(16 intermediate revisions by one other user not shown)
Line 1: Line 1:
  
 
+
 
 
 
 
 
 
 
 
 
 
 
 
 
  
 
== CMS help ==
 
== CMS help ==
Line 18: Line 12:
 
The CMS team can be contacted for support through: 
 
The CMS team can be contacted for support through: 
  
*The Climate Weather Science (CWS) helpdesk <span style="color:#1abc9c;">cws_help@nci.org.au</span>  
+
*The Climate Weather Science (CWS) helpdesk '''<span style="color:#16a085;">cws_help@nci.org.au</span>'''
 
*'''[http://climate-cms.wikis.unsw.edu.au/One-on-one_calls One-on-one videocall]'''  
 
*'''[http://climate-cms.wikis.unsw.edu.au/One-on-one_calls One-on-one videocall]'''  
 
*In person meetings with local&nbsp;'''[http://climate-cms.wikis.unsw.edu.au/CMS CMS team members]'''  
 
*In person meetings with local&nbsp;'''[http://climate-cms.wikis.unsw.edu.au/CMS CMS team members]'''  
 
*CodeBreak  
 
*CodeBreak  
  
The CWS help desk is the preferred contact method as it allows the CMS team to prioritize queries so as to set aside time for other CMS duties, provides transparency of open requests to all CMS team members , and gives the CMS team flexibility to cover for team absences. Simply outline your issue in an email to <u>cws_help@nci.org.au</u> to open a ticket on our helpdesk.
+
The CWS help desk is the preferred contact method as it allows the CMS team to prioritize queries so as to set aside time for other CMS duties, provides transparency of open requests to all CMS team members , and gives the CMS team flexibility to cover for team absences. Simply outline your issue in an email to '''<span style="color:#16a085;">cws_help@nci.org.au</span>''' to open a ticket on our helpdesk.
 
 
'''Note: '''We have [[Updated_support_level|updated our user support levels]] due to current staff shortage issues.
 
  
 
== Guidelines for help requests ==
 
== Guidelines for help requests ==
  
First of all, do not apologise or belittle yourself for asking a question! We all had to start one day. We all have different backgrounds with different areas of expertise. And most of all, we are all humans! None of us will know everything, all of us will be forgetful. Asking someone else is the best way to learn what we don't know or to realise what we have forgotten.
+
'''Before seeking assistance:'''
  
When seeking assistance, there are some steps that should be taken&nbsp;to&nbsp;make the most efficient use of everyone's time:
+
*Follow the&nbsp;'''[http://climate-cms.wikis.unsw.edu.au/Troubleshooting troubleshooting guide]'''
 +
*Read relevant documentation on our wiki or&nbsp;'''[https://climate-cms.org/ blog]'''
 +
*Google it&nbsp;!
  
*Follow the [[Troubleshooting|troubleshooting guide]]
+
'''When seeking assistance''':
*Have you read the documentation on this wiki (if it exists), any other relevant documentation, or looked on&nbsp;[https://climate-cms.org our blog]?
 
*Do you need to do some [[Training|training]] to improve your&nbsp;skills?
 
*Include all relevant information:
 
**what have you tried already that hasn't worked?
 
**provide some background for why you are doing the task that isn't working. Sometimes we might be able to suggest a different approach rather than trying to solve your specific error
 
**what machine are you running on: your machine (what OS), Gadi at NCI, OOD at NCI, accessdev at NCI or another server (give name)
 
**if working at NCI please supply your NCI user name
 
**if working on Gadi was the issue in a login session or on the PBS compute nodes?
 
**upload any code to [https://gist.github.com gist.github.com] or for more complex examples [https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/create-a-repo create a GitHub repository]. If you cannot put the code on Github because of licensing, put it on NCI and give us the path. '''Do not send copies of your code.'''
 
**if relevant, specify the modules that were loaded, or environment variables that were set. In particular if this is an error with the conda environment we support please include which version of the environment you are using.&nbsp;Tell us if you load modules in your .bashrc or .bash_profile files (not&nbsp;recommended practice!)
 
**if a command produces an error make sure to include the exact command run, including all arguments. The simplest is copy-paste.
 
**if a script produces an error make sure to include the exact name of the script and the exact way you execute the script. Copy-paste is the simplest here again.
 
**Add any relevant reference. It is unlikely you are referring to a paper-only resource, so include the link (or at least the URL), a quote from emails and webpage (with the address to the relevant page), forward emails, link to a paper... For example, if you say: "As I've seen on the wiki", "As per the article X" etc. you need to put the reference. 
 
*Please check to make sure any specified directories and/or files [[Tips:_Custom_file_permissions_at_creation|have group&nbsp;permissions set]] such that they can be accessed. Assume we can access the shared filesystems at NCI: /scratch and /g/data for your group. If we can't, we'll tell you what to do. '''/home directories are per default personal! You will need to change permissions for us to access!'''
 
*Where appropriate, reduce your query to a minimal&nbsp;reproducible example (Stack Overflow has a [https://stackoverflow.com/help/minimal-reproducible-example nice description of what this means], note that the formatting requirements are redundant)
 
*Please '''do not''' send code or error messages&nbsp;as screenshots or poorly formatted text&nbsp;
 
*Please submit new help requests for substantially new queries and not just append to existing queries. This makes sure any new&nbsp;query is visible to all team members, and can be triaged appropriately. We also have the satisfaction of completing a task rather than have it drag on interminably. Additionally, it provides us with a more organised database of queries and solutions.
 
  
To foster&nbsp;best practice software development for code housed&nbsp;in a GitHub repository (or similar) the following steps are preferred:&nbsp;
+
*Reduce'''&nbsp;'''your query if possible to a minimal reproducible example '''('''Stack Overflow has a&nbsp;'''[https://stackoverflow.com/help/minimal-reproducible-example nice description of what this means])'''
 +
*Submit separate help requests for significantly new queries instead of appending to existing tickets
 +
*Ensure required directories and/or files&nbsp;'''[http://climate-cms.wikis.unsw.edu.au/Tips:_Custom_file_permissions_at_creation have group permissions]&nbsp;'''that make them accessible to us. For example, NCI /home directories by default are not, so you will need to change their permissions, but typically we can access the NCI /scratch and /g/data for your group
 +
*Include all relevant information in your help request:
 +
**If a script/command generates an error, provide an exact reproduction of the script/command typed and error message
 +
**What have you tried so far to troubleshoot
 +
**Background info about your task (as we might be able to suggest instead a different approach) with links to any references invoked in your request
 +
**Platform used for your task (e.g., your machine/OS, NCI Gadi, OOD, accessdev). If NCI, supply your username, and if Gadi indicate if the issue was in a login session or the PBS compute nodes
 +
**Specify any environment variables set and modules loaded, and if loaded in your .bashrc or .bash_profile files (not recommended). For errors with the conda environment we support, include the environment version.&nbsp;
 +
**Upload any required code to '''[https://gist.github.com/ gist.github.com]&nbsp;'''or '''[https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/create-a-repo create a GitHub repository]&nbsp;'''for more complex examples. If barred by licensing issues, put it on NCI and provide the path. Never send copies of your code. 
 +
*Do not send code or error messages as screenshots or poorly formatted text
  
*Create an issue in the repo for the bug/problem
+
'''After seeking assistance''':
*Add a test for the specific bug where appropriate
 
*Document solution in the issue and&nbsp;refer&nbsp;to commits/pull requests: this creates a tight link between discussion of the problem and potential solutions with the code changes made to address points raised in the discussion. This could be done by the CMS team member helping you when appropriate.
 
*Resolve issue through a pull request mechanism. This could be done by the CMS team member helping you when appropriate.
 
*Close issue when fix has been committed
 
  
&nbsp;
+
*You should receive a reply to your query within 24 hours during normal business hours
 +
*We will provide a solution to your problem (if within scope), or a work-around, or an explanation for why it is currently unsolvable
 +
*You should expect updates required for current tickets to take at most a week during non-holiday periods
 +
*Consider if you need some '''[http://climate-cms.wikis.unsw.edu.au/Training training] '''to improve your skills
  
== What can users expect ==
+
If any of the above expectations are not being met, please contact the CMS team.
  
Users can expect:
+
&nbsp;
  
*to receive a reply to a query within 24 hours during normal business hours
+
&nbsp;
*have their problem solved if it is within scope, or a work-around suggested, and if not then an explanation of why their problem is currently not solvable
 
*where an update is required for a current ticket to&nbsp;wait no longer than a week during a non-holiday period
 
 
 
If any of the above expectations are not being met, contact the CMS team. We are only human and sometimes might inadvertently let slip some requests.
 
 
 
== Resources ==
 
 
 
Blog post on [https://codeblog.jonskeet.uk/2010/08/29/writing-the-perfect-question/ Writing the perfect question] &nbsp;
 
 
 
&nbsp; &nbsp;
 

Revision as of 19:02, 23 November 2022

 

CMS help

The CMS team supports CLEX members with computational issues: 

  • Running Models: we support several models (see navigation bar on the left) and assist with others, subject to limitations of scope and team resources. 
  • Data Analysis: we assist with analysis and general computing tasks on NCI machines, and offer only limited support on other sites or home machines as we possess neither control over nor familiarity with such systems.
  • Data Access and publishing: we offer assistance in publishing data and accessing climate data available at NCI.

The CMS team can be contacted for support through: 

The CWS help desk is the preferred contact method as it allows the CMS team to prioritize queries so as to set aside time for other CMS duties, provides transparency of open requests to all CMS team members , and gives the CMS team flexibility to cover for team absences. Simply outline your issue in an email to cws_help@nci.org.au to open a ticket on our helpdesk.

Guidelines for help requests

Before seeking assistance:

When seeking assistance:

  • Reduce your query if possible to a minimal reproducible example (Stack Overflow has a nice description of what this means)
  • Submit separate help requests for significantly new queries instead of appending to existing tickets
  • Ensure required directories and/or files have group permissions that make them accessible to us. For example, NCI /home directories by default are not, so you will need to change their permissions, but typically we can access the NCI /scratch and /g/data for your group
  • Include all relevant information in your help request:
    • If a script/command generates an error, provide an exact reproduction of the script/command typed and error message
    • What have you tried so far to troubleshoot
    • Background info about your task (as we might be able to suggest instead a different approach) with links to any references invoked in your request
    • Platform used for your task (e.g., your machine/OS, NCI Gadi, OOD, accessdev). If NCI, supply your username, and if Gadi indicate if the issue was in a login session or the PBS compute nodes
    • Specify any environment variables set and modules loaded, and if loaded in your .bashrc or .bash_profile files (not recommended). For errors with the conda environment we support, include the environment version. 
    • Upload any required code to gist.github.com or create a GitHub repository for more complex examples. If barred by licensing issues, put it on NCI and provide the path. Never send copies of your code.
  • Do not send code or error messages as screenshots or poorly formatted text

After seeking assistance:

  • You should receive a reply to your query within 24 hours during normal business hours
  • We will provide a solution to your problem (if within scope), or a work-around, or an explanation for why it is currently unsolvable
  • You should expect updates required for current tickets to take at most a week during non-holiday periods
  • Consider if you need some training to improve your skills

If any of the above expectations are not being met, please contact the CMS team.