<commit_before>CONFIGURING INSTITUTIONAL GRADING SCALES
========================================

Before Sakai 2.2, the Gradebook hard-coded available mappings of letter grades
to percentages in three Java classes. As of 2.2, configurable database-stored
grading scales are supported.

The scales are referred to only when creating a gradebook. From then on, the
gradebook's mappings of those scales to percentages stay under the control of
the instructor, just as they are now.

There are three ways to configure the new grading scales:

1) Do nothing. The first time someone creates a gradebook, the service code
will see that no grading scales exist and will automatically define them based
on the attributes of the old hard-coded grade mapping classes. This is a safe
cheap way to go unless you've already written code to customize the grade
mappings, in which case you'll want to take one of the other approaches so
that you can port your changes forward.

2) Write your own code to call the new GradebookService
setAvailableGradingScales and setDefaultGradingScale methods.

3) Define the grading scales and default grading scale via XML in:
gradebook/service/sakai-pack/src/webapp/WEB-INF/components.xml

Or if you're really brave you can write over the deployed copy in your Tomcat
directory:
components/sakai-gradebook-service-pack/WEB-INF/components.xml

There's a new Spring-managed bean defined there, which will call the
GradebookService at start-up time:
org_sakaiproject_service_gradebook_GradebookConfiguration

This is the easiest way to customize grading scales for your institution.
However, you might want to comment the configuration settings out after your
databases are updated. Otherwise they'll be unnecessarily re-written to the
database every time the system restarts. (No real harm will be done; it's just
kind of noisy.)


CONFIGURATION EXAMPLE: DEFAULT GRADING SCALES

This XML fragment would explicitly define the grading scales which are created
by default if none are found in the database.


<bean id="org_sakaiproject_service_gradebook_GradebookConfiguration"
  class="org.sakaiproject.service.gradebook.shared.GradebookConfiguration"
  init-method="init">
  <property name="gradebookService">
    <ref bean="org_sakaiproject_service_gradebook_GradebookService" />
  </property>

  <!-- Set up default system-wide grading scales. -->
  <property name="availableGradingScales">
    <list>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradePlusMinusMapping"/>
        <property name="name" value="Letter Grades with +/-"/>
        <property name="grades">
          <list>
            <value>A+</value>
            <value>A</value>
            <value>A-</value>
            <value>B+</value>
            <value>B</value>
            <value>B-</value>
            <value>C+</value>
            <value>C</value>
            <value>C-</value>
            <value>D+</value>
            <value>D</value>
            <value>D-</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>100.0</value>
            <value>95.0</value>
            <value>90.0</value>
            <value>87.0</value>
            <value>83.0</value>
            <value>80.0</value>
            <value>77.0</value>
            <value>73.0</value>
            <value>70.0</value>
            <value>67.0</value>
            <value>63.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeMapping"/>
        <property name="name" value="Letter Grades"/>
        <property name="grades">
          <list>
            <value>A</value>
            <value>B</value>
            <value>C</value>
            <value>D</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>90.0</value>
            <value>80.0</value>
            <value>70.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="PassNotPassMapping"/>
        <property name="name" value="Pass / Not Pass"/>
        <property name="grades">
          <list>
            <value>P</value>
            <value>NP</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>75.0</value>
            <value>0.0</value>
          </list>
        </property>
      </bean>
    </list>
  </property>

  <property name="defaultGradingScale" value="LetterGradePlusMinusMapping"/>
</bean>



CONFIGURATION EXAMPLE: CUSTOMIZED GRADING SCALES

This XML fragment would make five changes to the default grading scales:

  - The "Letter Grades with +/-" and "Pass / Not Pass" scales would stop
    appearing in new gradebooks.
  - A new mapping named "Letter Grades with !?" would appear in new
  gradebooks.
  - The "Letter Grades" scale would have its description changed to "Better
  Grades".
  - The default percentage mappings for that scale would be changed.
  - That scale would be made the default for new gradebooks.


<bean id="org_sakaiproject_service_gradebook_GradebookConfiguration"
  class="org.sakaiproject.service.gradebook.shared.GradebookConfiguration"
  init-method="init">
  <property name="gradebookService">
    <ref bean="org_sakaiproject_service_gradebook_GradebookService" />
  </property>

  <property name="availableGradingScales">
    <list>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeQuestionableMapping"/>
        <property name="name" value="Letter Grades with !?"/>
        <property name="grades">
          <list>
            <value>A!</value>
            <value>A?</value>
            <value>B!</value>
            <value>B?</value>
            <value>C!</value>
            <value>C?</value>
            <value>D!</value>
            <value>D?</value>
            <value>F!?</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>100.0</value>
            <value>90.0</value>
            <value>87.0</value>
            <value>80.0</value>
            <value>77.0</value>
            <value>70.0</value>
            <value>67.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeMapping"/>
        <property name="name" value="Better Grades"/>
        <property name="grades">
          <list>
            <value>A</value>
            <value>B</value>
            <value>C</value>
            <value>D</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>50.0</value>
            <value>30.0</value>
            <value>20.0</value>
            <value>10.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
    </list>
  </property>

  <property name="defaultGradingScale" value="LetterGradeMapping"/>
</bean>
<commit_msg>SAK-4309 Clarify current grading scale rules<commit_after>CONFIGURING INSTITUTIONAL GRADING SCALES
========================================

Before Sakai 2.2, the Gradebook hard-coded available mappings of letter grades
to percentages in three Java classes. As of 2.2, configurable database-stored
grading scales are supported.

The scales are referred to only when creating a gradebook. From then on, the
gradebook's mappings of those scales to percentages stay under the control of
the instructor, just as they are now.

There are three ways to configure the new grading scales:

1) Do nothing. The first time someone creates a gradebook, the service code
will see that no grading scales exist and will automatically define them based
on the attributes of the old hard-coded grade mapping classes. This is a safe
cheap way to go unless you've already written code to customize the grade
mappings, in which case you'll want to take one of the other approaches so
that you can port your changes forward.

2) Write your own code to call the new GradebookService
setAvailableGradingScales and setDefaultGradingScale methods.

3) Define the grading scales and default grading scale via XML in:
gradebook/service/sakai-pack/src/webapp/WEB-INF/components.xml

Or if you're really brave you can write over the deployed copy in your Tomcat
directory:
components/sakai-gradebook-service-pack/WEB-INF/components.xml

There's a new Spring-managed bean defined there, which will call the
GradebookService at start-up time:
org_sakaiproject_service_gradebook_GradebookConfiguration

This is the easiest way to customize grading scales for your institution.
However, you might want to comment the configuration settings out after your
databases are updated. Otherwise they'll be unnecessarily re-written to the
database every time the system restarts. (No real harm will be done; it's just
kind of noisy.)


GRADING SCALE RULES

The current code makes a few working assumptions which customizers must
follow to avoid surprises.

* A GradingScaleDefinition must contain a unique "uid" string which
permanently identifies that grading scale. If you configure a different
scale later with the same "uid", the new scale definition will overwrite
the old values.

* A GradingScaleDefinition must supply a "name" to be displayed to
instructors in the Gradebook.

* A GradingScaleDefinition should contain a list of "grades". These
are just character strings. They must be in top-to-bottom best-to-worst
order.

* A GradingScaleDefinition should contain a list of "defaultBottomPercents".
These are percentages. They must be ordered to match the "grades" list.
Currently, there must be as many "defaultBottomPercents" as there are
"grades", and the bottom of the list must be "0" or "0.0".

We hope to eliminate this restriction in a future release to allow for
non-calculated grades such as "Incomplete" which are, in effect, aliases
for "null" scores. Interested parties should follow progress and add
comments to "http://bugs.sakaiproject.org/jira/browse/SAK-4445".


CONFIGURATION EXAMPLE: DEFAULT GRADING SCALES

This XML fragment would explicitly define the grading scales which are created
by default if none are found in the database.


<bean id="org_sakaiproject_service_gradebook_GradebookConfiguration"
  class="org.sakaiproject.service.gradebook.shared.GradebookConfiguration"
  init-method="init">
  <property name="gradebookService">
    <ref bean="org_sakaiproject_service_gradebook_GradebookService" />
  </property>

  <!-- Set up default system-wide grading scales. -->
  <property name="availableGradingScales">
    <list>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradePlusMinusMapping"/>
        <property name="name" value="Letter Grades with +/-"/>
        <property name="grades">
          <list>
            <value>A+</value>
            <value>A</value>
            <value>A-</value>
            <value>B+</value>
            <value>B</value>
            <value>B-</value>
            <value>C+</value>
            <value>C</value>
            <value>C-</value>
            <value>D+</value>
            <value>D</value>
            <value>D-</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>100.0</value>
            <value>95.0</value>
            <value>90.0</value>
            <value>87.0</value>
            <value>83.0</value>
            <value>80.0</value>
            <value>77.0</value>
            <value>73.0</value>
            <value>70.0</value>
            <value>67.0</value>
            <value>63.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeMapping"/>
        <property name="name" value="Letter Grades"/>
        <property name="grades">
          <list>
            <value>A</value>
            <value>B</value>
            <value>C</value>
            <value>D</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>90.0</value>
            <value>80.0</value>
            <value>70.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="PassNotPassMapping"/>
        <property name="name" value="Pass / Not Pass"/>
        <property name="grades">
          <list>
            <value>P</value>
            <value>NP</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>75.0</value>
            <value>0.0</value>
          </list>
        </property>
      </bean>
    </list>
  </property>

  <property name="defaultGradingScale" value="LetterGradePlusMinusMapping"/>
</bean>



CONFIGURATION EXAMPLE: CUSTOMIZED GRADING SCALES

This XML fragment would make five changes to the default grading scales:

  - The "Letter Grades with +/-" and "Pass / Not Pass" scales would stop
    appearing in new gradebooks.
  - A new mapping named "Letter Grades with !?" would appear in new
  gradebooks.
  - The "Letter Grades" scale would have its description changed to "Better
  Grades".
  - The default percentage mappings for that scale would be changed.
  - That scale would be made the default for new gradebooks.


<bean id="org_sakaiproject_service_gradebook_GradebookConfiguration"
  class="org.sakaiproject.service.gradebook.shared.GradebookConfiguration"
  init-method="init">
  <property name="gradebookService">
    <ref bean="org_sakaiproject_service_gradebook_GradebookService" />
  </property>

  <property name="availableGradingScales">
    <list>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeQuestionableMapping"/>
        <property name="name" value="Letter Grades with !?"/>
        <property name="grades">
          <list>
            <value>A!</value>
            <value>A?</value>
            <value>B!</value>
            <value>B?</value>
            <value>C!</value>
            <value>C?</value>
            <value>D!</value>
            <value>D?</value>
            <value>F!?</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>100.0</value>
            <value>90.0</value>
            <value>87.0</value>
            <value>80.0</value>
            <value>77.0</value>
            <value>70.0</value>
            <value>67.0</value>
            <value>60.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
      <bean
      class="org.sakaiproject.service.gradebook.shared.GradingScaleDefinition"
      >
        <property name="uid" value="LetterGradeMapping"/>
        <property name="name" value="Better Grades"/>
        <property name="grades">
          <list>
            <value>A</value>
            <value>B</value>
            <value>C</value>
            <value>D</value>
            <value>F</value>
          </list>
        </property>
        <property name="defaultBottomPercents">
          <list>
            <value>50.0</value>
            <value>30.0</value>
            <value>20.0</value>
            <value>10.0</value>
            <value>00.0</value>
          </list>
        </property>
      </bean>
    </list>
  </property>

  <property name="defaultGradingScale" value="LetterGradeMapping"/>
</bean>

{'fraction_non_alphanumeric': 0.11650368948347231, 'fraction_numerical': 0.013858059871617973, 'mean_word_length': 2.4413707679603633, 'pattern_counts': {'":': 0, '<': 437, '<?xml version=': 0, '>': 437, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7650492', 'n_tokens_mistral': 4971, 'n_tokens_neox': 4706, 'n_words': 1315}