Skip to content

Latest commit

 

History

History
131 lines (88 loc) · 14 KB

CONTRIBUTING.md

File metadata and controls

131 lines (88 loc) · 14 KB
Raw

How to Contribute

We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.

Contents

Contributor License Agreement

Contributions to this project must be accompanied by a signed Contributor Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

How to create or modify a task

To write a new task, or to update an existing task, follow the guidance below.

For contributors, or users making a their own custom version of the project, if you add or change specific properties of tasks (filename, title, SortString, Description or Tags) you can run the scripts which update documents like the top-level checklist.md, e.g. scripts/build_all.py (or scripts/build_from_template.py). These scripts have usage instructions in their header comments.

Examples

This project is a checklist of tasks, and the files containing the descriptions of those tasks are its principal deliverable.

Each task is defined in a single GitHub Flavored Markdown file in the tasks subdirectory of the project root. Some tasks are one of a pair, with a one-off Initial task to learn how to do something or set some feature up, and a related Regular task to do that thing, or maintain that feature regularly over time.

Each task file should have these required and optional features:

  1. [Required]: Give tasks a filename which is unique, fairly short, identifies the main concept of the task and has a .md file extension. Tasks are referred to by their filename (not by their SortString), and so it is preferable not to change a tasks's filename once it has been merged into the project's main branch. If you do change a task's filename, you must also find and similarly change any internal links to the task within this project.

  2. [Required]: The first line in every task markdown file is a header image, exactly like this:

    ![Global Enablement & Learning](/img/gel_banner_logo_tech-partners.jpg)

  3. [Required]: A single level 1 ATX Heading near the top of the file, like this: # Task Title

    The text following the '# ' becomes the task's title when it is listed in tables of contents. It is rendered in HTML as <h1>Task Title</h1>.

    There should be no more than one level 1 heading in a task file. There can be any number of level 2 to level 6 headings in a task.

  4. [Required]: An HTML comment block containing a series of name value pairs separated by a colon, like this:

     <!--
 SortString: 042
 Description: The Answer to Life, the Universe and Everything
 Tags: Initial,InProgress,New
 Topic: SAS Administration
 Essential: -
 Authors: Charles Babbage,Douglas Adams,Tim Berners-Lee,John Gruber
 -->

    The following key-value pairs should all be included, each with the key and all its comma-separated values on one line:

    Name Notes on values
    SortString Used for sorting tasks within checklist tables.
    Not a key. Avoid written references to tasks by their SortString. Instead, refer to tasks by their markdown filename which should preferably remain constant.

    Note: in previous checklists we often referred to tasks by their id, but this is now avoided because task SortStrings are expected to change from time to time. Changing a task's SortString value should never break a reference to the task.

    Intended to be used for sorting tasks in a checklist.
    May change arbitrarily when we re-order tasks.
    Suggest 4-digit number.

    Note: Initially tasks had SortString values separated by 10 - 0010, 0020 etc. - to allow room for new tasks to be inserted in between existing ones. If you wish to insert your task between existing tasks you are welcome to choose a number between two existing tasks, e.g. to have a task sorted between the tasks with SortString 0120 and 0130, you could give yours a SortString value of 0125. Later, to insert yet another task before that one, the next task could be given a SortString value of 0123, and so on. You may change the SortString of other tasks if you have to, in order to create space in the sequence for your task. Occasionally we may revise some or all SortString values to create more space. Do not rely on the SortString of any task remaining constant over time.
    Description A short description of the task, typically no more than 200-300 characters. If you need a longer description, consider whether this task should be split into two or more smaller tasks.
    Tags A comma-separated list of tags, all on one line, used for filtering tables of content in the checklist.md and other documents generated from templates. The order of these tags is not important.
    Other tag groups may be added in future, and tasks may be given tags from a new tag group retrospectively.

    Include exactly one tag from each of the following required groups:
    • Initial or Regular (temporal adjective tag - if you intend both make two tasks, one for 'define how to do it' and one for 'do it')
    • Backlog, InProgress, Review or Done status tag for tracking progress in task development. Only tasks tagged as Done appear in the main checklist.
    • Legacy or New for the tasks's provenance. For tasks that had equivalents in earlier checklists for SAS Viya 3 and SAS 9. The detail of these tasks in SAS Viya 2020.1 and later may differ very significantly from their earlier equivalents.
    Authors A comma-separated list full names (firstname lastname) of authors who wrote a substantial portion of the words in the task, even if they were copied here from another source. Use this tag - with the author's consent if possible - to acknowledge someone's contribution to the task content and avoid taking undue credit for another author's work. Adding your own name is optional - omit yours if you wish, though your username in git's commit history might enable someone to identify your contribution. You should not add your name to the authors list if you only made minor edits to a task, e.g. for spelling, grammar, punctuation, consistency or formatting. It is not necessary to name the authors of material you reference from your task.
    Frequency For all regular tasks, and regular tasks only, specify when we would suggest the task be done. Keep as short as possible. Example values: Hourly, Daily, Weekly, Monthly, Quarterly, Annually, When troubleshooting. Other values are okay, but 'as needed' is a bit too vague: make a suggestion. The reader is free to disagree.
    Topic One of:
    • CAS
    • Kubernetes & IT Admin
    • Observability
    • Organization & Governance
    • PostgreSQL
    • SAS Administration
    • SAS Programming Run-time
    Note: New topics should be approached with care, because topics have their own tables in the tasks_by_topic_template.md (so you should edit that template if you use a new topic), and topics with a single task in them are of questionable value. Tasks often span topics - pick the one which suits the task best; there are not so many tasks that a task spanning two topics but listed under only one of them will likely be overlooked by a diligent reader.
    Essential One of
    • Yes
    • -
    The value '-' means recommended but not absolutely essential, but at a glance it is easier to see the rows with a yes if the rest are marked '-' instead of 'No' or 'Recommended'.

  5. [Optional] A When: line.

    When should an administrator (or someone they coordinate with) do this task? A When: line is optional but usually included. Omit it if there is no particular time you think the task should be done. However, there is a 'best' time to perform most tasks in the checklist. If you do not include a 'When:' line, someone else may do so later.

    Examples:

    • When: After platform changes
    • When: Before and/or after platform changes and in tandem with organizational changes
    • When: At the beginning and end of a period of troubleshooting activity
    • When: Regularly per housekeeping schedule

    You are free to describe when the task should be done in your own words, if none of the examples above are appropriate to your task.

  6. [Optional]: Above each of two or more separate ideas, a level 2 to 6 ATX Heading.

    • A level 2 subheading looks like this: ## Brief description of part of the task
    • A level 3 subheading looks like this: ### Brief description of a sub-part the task or subordinate concept
    • ...and so on.

    Subheadings should be different from the task title, and are best included either:

    • if you need multiple subheadings to separate ideas that are part of the same tasks, or
    • if your task represents a single idea, but the task title doesn't adequately describe the task. For example, the title "Security Policy" is pleasingly short and the task document only presents one idea, but the task has one level 2 subheading ("Write and maintain a security policy that covers the SAS Viya deployment"). There are no other level 2 subheadings. This neatly keeps the table of contents entry for the task short, but explains what the task's idea is more clearly.

    If your task title adequately describes the task and the task only presents one idea, omit level 2 and lower subheadings.

  7. [Required]: Body text describing what the task is, why you should consider doing it and where to find instructions. In order of preference from most to least preferable, you may:

    • Refer to existing instructions, when suitable instructions are publically available. If the existing instructions are only available in the form of unofficial or community-created content such as a blog post or video, consider asking for official SAS public documentation to be written to cover the topic. Not every topic we may write about will be suitable for official SAS public documentation.
    • When suitable instructions are NOT publically available, ask for official documentation to be written and/or write a blog post or other article describing the task and how to do it, and publish it, e.g. in the SAS Communities Library. Then, write (or finish writing) a task here and refer to that post (e.g. using a permalink) in the body the task. If the instructions need to be updated, update your existing post or publish a new one, and where necessary update the references in the task so that they direct the reader to a current version of the instructions.
    • Include instructions directly in the task's body text. This may seem easier, but it has some disadvantages, and is not the preferred approach. Good instructions take time to write and must be maintained. We think it is best to provide instructions in other, established locations, and not to turn this checklist into yet another source of detailed instructions.

  8. [Optional] One or more See also: lines.

    Your task's body text will usually contain one or more references to other resources. If you like to include links in your text that is fine. But a See also: line is another option, which may suit tasks which refer to lists of resources when you do not need to write a story about them. Include a word or short phrase inside square brackets at the end of the link to indicate what sort of resource it is.

    Here are some examples:

    A See also: line right before the link back to the top-level checklist is a good way to 'pair' your task with a related task, e.g. between a pair of tasks where there is a one-time initial 'set a thing up or learn how to do a thing' task, and an corresponding regular 'do the thing' task. Each task can have a See also: line referring the reader to the other in the pair.

  9. [Required]: A link back to the top-level checklist.md. The Markdown for this link looks like this:

    [Back to checklist](../checklist.md)

Link to the latest documentation

If your task references SAS documentation, edit URLs at go.documentation.sas.com, replace the version number in the URL (e.g. /v_031/) with 'default' (e.g. /default/) to link to the latest version of the documentation. So, for example the URL https://go.documentation.sas.com/doc/en/sasadmincdc/v_037/k8sag/p1it185kd37v25n1aoybu799tpk4.htm becomes https://go.documentation.sas.com/doc/en/sasadmincdc/default/k8sag/p1it185kd37v25n1aoybu799tpk4.htm. If a new version of this doc page is released in future, the modified URL with 'default' instead of a version number should redirect to the latest version.

Links must work outside SAS

This project is public. All URLs you link to should be accessible outside SAS. Do not link to pages or other resources on SAS-internal sites, such as sww.sas.com.