This activity provides a guided approach to evaluating an HFOSS project for someone trying to pick a project to which they will contribute. The activity is designed with particular attention to instructors who need to identify an HFOSS project that they will use in a class. The characteristics evaluated include the pattern of contributions, pattern of commits, programming languages used, and more.

+

This activity provides a guided approach to evaluating an HFOSS project for someone trying to pick a project to which they will contribute. The activity is designed with particular attention to instructors who need to identify an HFOSS project that they will use in a class. The characteristics evaluated include the pattern of contributions, pattern of commits, programming languages used, and more. This activity uses OpenMRS as a sample project to evaluate.

|prerequisites=

|prerequisites=

* Completion of [[FOSS Field Trip (Activity)]] or an understanding of GitHub and OpenHub

* Completion of [[FOSS Field Trip (Activity)]] or an understanding of GitHub and OpenHub

Line 16:

Line 16:

=== Background ===

=== Background ===

−

Not all projects are equally good for someone wanting to become a contributor. Some projects just don't welcome new contributors, or are not well organized to support getting new people up to speed. Other projects are welcoming to new contributors and provide clear pathways to join the community. Anyone considering becoming a contributor to a project should have some idea what to look for. While these evaluation criteria are not foolproof, they at least provide a starting point and framework of things to consider.

+

Not all projects are equally good for someone wanting to become a contributor. Some projects just don't welcome new contributors, or are not well organized to support getting new people up to speed. Other projects are welcoming to new contributors and provide clear pathways to join the community. Anyone considering becoming a contributor to a project should have some idea what to look for in evaluating whether a project is a good choice for becoming a contributor. While these evaluation criteria are not foolproof, they at least provide a starting point and framework of things to consider.

=== Directions ===

=== Directions ===

Line 22:

Line 22:

==== Walk through of an evaluation of the OpenMRS project ====

==== Walk through of an evaluation of the OpenMRS project ====

−

There are many criteria that should be looked at when determining if a project is appropriate to use in your class. These criteria are prioritized and explored below. The Project Evaluation Rubric contains instructions for each criterion and, in some cases, questions to guide your thinking. You will place your findings, including notes, in the rubric.

+

There are many criteria that should be looked at when determining if a project is appropriate to use in your class. These criteria are prioritized and explored below. The [http://foss2serve.org/index.php/Project_Evaluation_Rubric_(Activity) Project Evaluation Rubric] contains instructions for each criterion and directions on scoring criteria. Place a copy of the Project Evaluation Rubric on your wiki page. Include your findings (notes and the answers to the below questions) in your copy of the rubric, along with your scores for each. <br><br>

'''Licensing''' - An important first step is to identify the license used by the project. An open source project must specify that others are free to use it, redistribute it, change it, and redistribute modified versions too. An extensive list of open source licenses can be found at https://opensource.org/licenses/alphabetical. A list of free software licenses can be found at https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses

'''Licensing''' - An important first step is to identify the license used by the project. An open source project must specify that others are free to use it, redistribute it, change it, and redistribute modified versions too. An extensive list of open source licenses can be found at https://opensource.org/licenses/alphabetical. A list of free software licenses can be found at https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses

−

* Go to the OpenMRS core repository (https://github.com/openmrs/openmrs-core). On the repository page, click on the "< > Code" tab below the repository name. Look at the information line below the tabs for a license name (see below image). Note: if the license does not appear here, look at the top level files in the repository for a license file.

+

* Go to the OpenMRS core repository (https://github.com/openmrs/openmrs-core). On the repository page, click on the "< > Code" tab below the repository name. Look at the information line below the tabs for a license name (see below image). Note: if the license does not appear here, or if a project is not on GitHub, look at the top level files in the repository for a license file.

* Does OpenMRS use an OSI approved open source license? Enter your findings in the rubric.

* Does OpenMRS use an OSI approved open source license? Enter your findings in the rubric.

[[File:ProjEval-Img1.jpg|600px|thumb|center]]

[[File:ProjEval-Img1.jpg|600px|thumb|center]]

−

'''Languages''' - The language(s) used in the project is an essential consideration for your students. If the project is written in a language(s) that your students are already familiar with, or better yet, well versed in, this is one less hurdle to overcome.

+

'''Language''' - The language(s) used in the project is an essential consideration for your students. If the project is written in a language(s) that your students are already familiar with, or better yet, well versed in, this is one less hurdle to overcome.

* Click on the language details bar (see above image). Record the top three languages used and the percentage for each.

* Click on the language details bar (see above image). Record the top three languages used and the percentage for each.

−

'''Activity''' - To support student participation a project should be reasonably active. Number of commits can be used as an indicator of activity. Little to no activity over a year, for example, may indicate that the project is dead.

+

'''Activity''' - To support student participation, a project should be reasonably active. Number of commits can be used as an indicator of activity. Little to no activity over a year, for example, may indicate that the project is dead, or mature and not being actively developed.

* Click the "Graphs" tab then select "Commits"

* Click the "Graphs" tab then select "Commits"

−

* Assuming "Active" means that approximately two-thirds of the weeks in a given quarter have commits, determine whether each quarter was active over the last year by recording yes or no in the rubric. Note: you can use approximate delineations for each quarter.

+

* If we define "Active" as meaning that a majority of the weeks in a given quarter have commits, determine whether each quarter was active over the last year and place your findings in the rubric. Note: since the definition of "active" is approximate, assess each quarter at a glance rather than by actual count of commits.

−

'''Number of contributors''' - A suitable project must have an active user community. A common fossism states that "It's all about community." The community members are great resources for both faculty and students and they begin to learn about a new project, its culture, and norms.

+

'''Number of contributors''' - A common fossism states that "It's all about community," so a suitable project should have an active user community. The community members are great resources for both faculty and students as they begin to learn about a new project, its culture, and norms.

* Click the "< > Code" tab. The number of contributors is listed above the language details bar. Determine how many contributors there are to the OpenMRS core project and enter your findings in the rubric.

* Click the "< > Code" tab. The number of contributors is listed above the language details bar. Determine how many contributors there are to the OpenMRS core project and enter your findings in the rubric.

'''Size''' - The size of the project is likely to be a factor depending on the level of your students. A large project that is built using many various technologies is likely to seem overwhelming to a CS2 student, for example, but may be a perfect fit for a senior capstone course. A simple first step is to determine how large the project is, additional research could be done to ascertain complexity. By default, Github does not provide information about how many lines of code there are in a repository or its size. You can however install an extension for Google Chrome that will display the size. Follow the instructions below to install the extension.

'''Size''' - The size of the project is likely to be a factor depending on the level of your students. A large project that is built using many various technologies is likely to seem overwhelming to a CS2 student, for example, but may be a perfect fit for a senior capstone course. A simple first step is to determine how large the project is, additional research could be done to ascertain complexity. By default, Github does not provide information about how many lines of code there are in a repository or its size. You can however install an extension for Google Chrome that will display the size. Follow the instructions below to install the extension.

Line 47:

Line 47:

# How many open (for OpenMRS look at "ready for work") issues are there?

# How many open (for OpenMRS look at "ready for work") issues are there?

# How many closed issues are there?

# How many closed issues are there?

−

# When was the fifth issue opened (for OpenMRS look at the "ready for work" issues)?

+

# When was the fifth issue opened (for OpenMRS look at the "ready for work" issues)?

+

# Based on browsing the table, and clicking on some of the table cells, assess whether issues are actively being added and resolved

'''New contributor''' - The project should appear welcoming to new contributors. Some clear examples of this would be links to getting started pages or information on ways to become involved. These pages, in turn, should include additional detail about '''how''' to become involved, as well as information about '''how''' to connect with the community.

'''New contributor''' - The project should appear welcoming to new contributors. Some clear examples of this would be links to getting started pages or information on ways to become involved. These pages, in turn, should include additional detail about '''how''' to become involved, as well as information about '''how''' to connect with the community.

* Browse the repository and associated links, is there any indication that the project welcomes new contributors? Indicate which of the following are present and provide links in the rubric. Note: for OpenMRS you will find that the link at the top to openmrs.org and the link toward the bottom of the repository page to the OpenMRS wiki quite useful!

* Browse the repository and associated links, is there any indication that the project welcomes new contributors? Indicate which of the following are present and provide links in the rubric. Note: for OpenMRS you will find that the link at the top to openmrs.org and the link toward the bottom of the repository page to the OpenMRS wiki quite useful!

Line 56:

Line 57:

'''Community norms''' - The way in which community members interact with one another is equally important, especially for student involvement. You do not want to point students to a project that advocates or permits lewd and unprofessional behavior.

'''Community norms''' - The way in which community members interact with one another is equally important, especially for student involvement. You do not want to point students to a project that advocates or permits lewd and unprofessional behavior.

* Some projects provide a "Code of Conduct", yet others do not. It it quite possible that you will find the code of conduct more quickly by doing a Google search. For OpenMRS you should look in the "Developer Guide" (link along with left side in the OpenMRS wiki) and then choose "Conventions"

* Some projects provide a "Code of Conduct", yet others do not. It it quite possible that you will find the code of conduct more quickly by doing a Google search. For OpenMRS you should look in the "Developer Guide" (link along with left side in the OpenMRS wiki) and then choose "Conventions"

−

* You should also review communication norms to determine if there any indications of rude or inappropriate behavior? Again, this could be a bit time consuming since you would first have to determine the type of communication typically used by community members and then locate the appropriate artifacts. For OpenMRS, click the "TALK" link at the top of the OpenMRS wiki page and review the communications that occurred for two of the topics. Choose two that have at least 5 members and 15 or more replies.

+

* You should also review some actual communications to determine if there any indications of rude or inappropriate behavior. This could be quite time consuming since you would first have to determine the type of communication typically used by community members and then locate and review the appropriate artifacts. For OpenMRS, click the "TALK" link at the top of the OpenMRS wiki page and review the communications that occurred for two of the topics. Choose two that have at least 5 members and 15 or more replies.

−

* Answer the following in the rubric.

+

* Record the following in the rubric.

# Provide three observations about the OpenMRS Code of Conduct.

# Provide three observations about the OpenMRS Code of Conduct.

−

# Provide three observations about the type of communication that occurred between community members on TALK.

+

# Provide three observations about the type of communication that occurred between community members on TALK. Is there any indication of rude or inappropriate behavior?

−

'''User base''' - A project will not thrive without a core user-base. The user-base consists clients, people who use the product on a day-to-day basis. They provide the development team with necessary feedback about the project, what works, what doesn't and what new features they might like to see. If no one is using the product then developers are likely to abandon it. Browse the repository and related links. In the rubric record your answers to the following.

+

'''User base''' - A project will not thrive without a core user-base. The user-base consists of clients, people who use the product on a day-to-day basis. They provide the development team with necessary feedback about the project, what works, what doesn't and what new features they might like to see. If no one is using the product then developers are likely to abandon it. Browse the repository and related links.

+

* In the rubric record your answers to the following.

# Does there appear to be a user base?

# Does there appear to be a user base?

# Are there instructions for downloading and setting up the software for use by clients?

# Are there instructions for downloading and setting up the software for use by clients?

Line 67:

Line 69:

=== Deliverables ===

=== Deliverables ===

−

POSSE: On your user wiki page, a section that contains the Project Evaluation rubric describing your evaluation of OpenMRS as a suitable project for your course.

* For a more introductory class, assessment can be based on simply answering the question included above for evaluating OpenMRS. This generally requires nothing more than being able to point and click and record the correct information. Students will get a simple view of evaluation in one context

−

* How will learning will be measured?

+

* For more advanced students, some possible extensions would include:

−

* Include sample assessment questions/rubrics.

+

** Providing the activity as shown above, but having them do an evaluation for another HFOSS project, perhaps one not on GitHub

+

** Having students assess several HFOSS projects

+

** Adding additional assessment questions that require interpretation or comparison of data for various criteria

+

** This particular activity can be the basis for a larger discussion or reflection about the general problem of product evaluation, selection, and comparison. Those issues are relevant whether the product is FOSS, proprietary, or developed in-house.

+

** This activity could also prompt discussion of measurement problems including qualitative vs. quantitative measures, development of frameworks for evaluation, and weighting of criteria to reach an overall evaluation conclusion

+

+

The table below provides an outline of a rubric reflecting the recommended evaluation criteria.

{| border="1" class="wikitable"

{| border="1" class="wikitable"

Line 86:

Line 94:

! Level 4 (exceptional)

! Level 4 (exceptional)

|-

|-

−

| '''The purpose of the project'''

+

| '''Licensing'''

|

|

|

|

Line 93:

Line 101:

|-

|-

−

| '''Why the project is open source'''

+

| '''Languages'''

+

|

+

|

+

|

+

|

+

|-

+

| '''Activity'''

+

|

+

|

+

|

+

|

+

|-

+

| '''Contributors'''

+

|

+

|

+

|

+

|

+

|-

+

| '''Issue Tracker'''

+

|

+

|

+

|

+

|

+

|-

+

| '''New Contributor'''

+

|

+

|

+

|

+

|

+

|-

+

| '''Norms'''

+

|

+

|

+

|

+

|

+

|-

+

| '''Client Base'''

|

|

|

|

Line 103:

Line 147:

=== Comments ===

=== Comments ===

−

* What should the instructor know before using this activity?

+

* The criteria defined above are general, but the specific ways of evaluating each criterion will vary by project. OpenMRS provides a good example for evaluating each criterion for projects on GitHub. Projects on other forges will require different approaches to evaluate many of the criteria.

−

* What are some likely difficulties that an instructor may encounter using this activity?

+

* There tend to be similarities in the way HFOSS projects are structured. If you repeat this evaluation for a series of candidate projects, it gets easier to do the evaluation quickly. The situation is similar to the time it takes to learn a first or second programming language vs a sixth or seventh programming language. After doing a few, you know what to look for.

=== Variants and Adaptations ===

=== Variants and Adaptations ===

Line 117:

Line 161:

*# [http://youtu.be/MAGet2D5o2c Mission critical criteria]

*# [http://youtu.be/MAGet2D5o2c Mission critical criteria]

*# [http://youtu.be/e4lnIXjqczU Secondary criteria]

*# [http://youtu.be/e4lnIXjqczU Secondary criteria]

+

* Other sources that may help you select a project include:

+

** [https://www.theopensourceway.org/book/The_Open_Source_Way-How_to_tell_if_a_FLOSS_project_is_doomed_to_FAIL.html How to Tell if a FLOSS Project is Doomed to Fail] or a summarized version: [https://opensource.com/life/15/7/why-your-open-source-project-failing Why your open source project is failing]

+

** [http://producingoss.com/ Producing Open Source Software (2017)] by Karl Fogel is a great reference for many topics. Chapter 2, Getting Started, discusses things a project should address to be successful. That chapter can also be read as a checklist for things a project should have completed if you are considering being a contributor.

Suggestions for an open source community member who is working in conjunction with the instructor.

+

None at this time.

Line 145:

Line 195:

[[Category:Learning Activity]]

[[Category:Learning Activity]]

[[Category:Use and Evaluate]]

[[Category:Use and Evaluate]]

+

[[Category: Good Draft]]

Latest revision as of 13:22, 25 June 2017

Title

Project Evaluation

Overview

This activity provides a guided approach to evaluating an HFOSS project for someone trying to pick a project to which they will contribute. The activity is designed with particular attention to instructors who need to identify an HFOSS project that they will use in a class. The characteristics evaluated include the pattern of contributions, pattern of commits, programming languages used, and more. This activity uses OpenMRS as a sample project to evaluate.

Background

Not all projects are equally good for someone wanting to become a contributor. Some projects just don't welcome new contributors, or are not well organized to support getting new people up to speed. Other projects are welcoming to new contributors and provide clear pathways to join the community. Anyone considering becoming a contributor to a project should have some idea what to look for in evaluating whether a project is a good choice for becoming a contributor. While these evaluation criteria are not foolproof, they at least provide a starting point and framework of things to consider.

Directions

Walk through of an evaluation of the OpenMRS project

There are many criteria that should be looked at when determining if a project is appropriate to use in your class. These criteria are prioritized and explored below. The Project Evaluation Rubric contains instructions for each criterion and directions on scoring criteria. Place a copy of the Project Evaluation Rubric on your wiki page. Include your findings (notes and the answers to the below questions) in your copy of the rubric, along with your scores for each.

Go to the OpenMRS core repository (https://github.com/openmrs/openmrs-core). On the repository page, click on the "< > Code" tab below the repository name. Look at the information line below the tabs for a license name (see below image). Note: if the license does not appear here, or if a project is not on GitHub, look at the top level files in the repository for a license file.

Does OpenMRS use an OSI approved open source license? Enter your findings in the rubric.

Language - The language(s) used in the project is an essential consideration for your students. If the project is written in a language(s) that your students are already familiar with, or better yet, well versed in, this is one less hurdle to overcome.

Click on the language details bar (see above image). Record the top three languages used and the percentage for each.

Activity - To support student participation, a project should be reasonably active. Number of commits can be used as an indicator of activity. Little to no activity over a year, for example, may indicate that the project is dead, or mature and not being actively developed.

Click the "Graphs" tab then select "Commits"

If we define "Active" as meaning that a majority of the weeks in a given quarter have commits, determine whether each quarter was active over the last year and place your findings in the rubric. Note: since the definition of "active" is approximate, assess each quarter at a glance rather than by actual count of commits.

Number of contributors - A common fossism states that "It's all about community," so a suitable project should have an active user community. The community members are great resources for both faculty and students as they begin to learn about a new project, its culture, and norms.

Click the "< > Code" tab. The number of contributors is listed above the language details bar. Determine how many contributors there are to the OpenMRS core project and enter your findings in the rubric.

Size - The size of the project is likely to be a factor depending on the level of your students. A large project that is built using many various technologies is likely to seem overwhelming to a CS2 student, for example, but may be a perfect fit for a senior capstone course. A simple first step is to determine how large the project is, additional research could be done to ascertain complexity. By default, Github does not provide information about how many lines of code there are in a repository or its size. You can however install an extension for Google Chrome that will display the size. Follow the instructions below to install the extension.

You should now see the repository size next to license type. Record the size in the rubric.

Issue tracker - The issue tracker can provide insight into the health of a project. An active issue tracker should highlight issues that clients/developers have logged as well as an indication that these issues are being addressed.

Click "Issues" (note: this should appear next to "< > Code"; if you do not see this tab, then there are no issues logged in Github). OpenMRS uses a third-party issue tracker - click the link to openmrs.org located near the top of the repository page, scroll to the bottom and click the "OpenMRS Issue Tracking" link. Scroll to the table labeled "Two Dimensional Filter Statistics: All JIRA Tickets" located near the bottom of the page. Provide answers to the following in the rubric.

How many open (for OpenMRS look at "ready for work") issues are there?

How many closed issues are there?

When was the fifth issue opened (for OpenMRS look at the "ready for work" issues)?

Based on browsing the table, and clicking on some of the table cells, assess whether issues are actively being added and resolved

New contributor - The project should appear welcoming to new contributors. Some clear examples of this would be links to getting started pages or information on ways to become involved. These pages, in turn, should include additional detail about how to become involved, as well as information about how to connect with the community.

Browse the repository and associated links, is there any indication that the project welcomes new contributors? Indicate which of the following are present and provide links in the rubric. Note: for OpenMRS you will find that the link at the top to openmrs.org and the link toward the bottom of the repository page to the OpenMRS wiki quite useful!

Are there instructions for downloading and installing the development environment?

Are communication mechanisms, such as IRC, list serves, you can join, meeting notices, etc. apparent?

Is there a discussion platform? If so, how recent are the responses?

Is there Web presence? This might include information about the project, how to get started as a developer, links to blogs, links to IRC logs, links to pages that contain information about coding standards and the code submission process.

Community norms - The way in which community members interact with one another is equally important, especially for student involvement. You do not want to point students to a project that advocates or permits lewd and unprofessional behavior.

Some projects provide a "Code of Conduct", yet others do not. It it quite possible that you will find the code of conduct more quickly by doing a Google search. For OpenMRS you should look in the "Developer Guide" (link along with left side in the OpenMRS wiki) and then choose "Conventions"

You should also review some actual communications to determine if there any indications of rude or inappropriate behavior. This could be quite time consuming since you would first have to determine the type of communication typically used by community members and then locate and review the appropriate artifacts. For OpenMRS, click the "TALK" link at the top of the OpenMRS wiki page and review the communications that occurred for two of the topics. Choose two that have at least 5 members and 15 or more replies.

Record the following in the rubric.

Provide three observations about the OpenMRS Code of Conduct.

Provide three observations about the type of communication that occurred between community members on TALK. Is there any indication of rude or inappropriate behavior?

User base - A project will not thrive without a core user-base. The user-base consists of clients, people who use the product on a day-to-day basis. They provide the development team with necessary feedback about the project, what works, what doesn't and what new features they might like to see. If no one is using the product then developers are likely to abandon it. Browse the repository and related links.

In the rubric record your answers to the following.

Does there appear to be a user base?

Are there instructions for downloading and setting up the software for use by clients?

Deliverables

Notes for Instructors

The remaining sections of this document are intended for the instructor. They are not part of the learning activity that would be given to students.

Assessment

For a more introductory class, assessment can be based on simply answering the question included above for evaluating OpenMRS. This generally requires nothing more than being able to point and click and record the correct information. Students will get a simple view of evaluation in one context

For more advanced students, some possible extensions would include:

Providing the activity as shown above, but having them do an evaluation for another HFOSS project, perhaps one not on GitHub

Having students assess several HFOSS projects

Adding additional assessment questions that require interpretation or comparison of data for various criteria

This particular activity can be the basis for a larger discussion or reflection about the general problem of product evaluation, selection, and comparison. Those issues are relevant whether the product is FOSS, proprietary, or developed in-house.

This activity could also prompt discussion of measurement problems including qualitative vs. quantitative measures, development of frameworks for evaluation, and weighting of criteria to reach an overall evaluation conclusion

The table below provides an outline of a rubric reflecting the recommended evaluation criteria.

Criteria

Level 1 (fail)

Level 2 (pass)

Level 3 (good)

Level 4 (exceptional)

Licensing

Languages

Activity

Contributors

Issue Tracker

New Contributor

Norms

Client Base

Comments

The criteria defined above are general, but the specific ways of evaluating each criterion will vary by project. OpenMRS provides a good example for evaluating each criterion for projects on GitHub. Projects on other forges will require different approaches to evaluate many of the criteria.

There tend to be similarities in the way HFOSS projects are structured. If you repeat this evaluation for a series of candidate projects, it gets easier to do the evaluation quickly. The situation is similar to the time it takes to learn a first or second programming language vs a sixth or seventh programming language. After doing a few, you know what to look for.

Producing Open Source Software (2017) by Karl Fogel is a great reference for many topics. Chapter 2, Getting Started, discusses things a project should address to be successful. That chapter can also be read as a checklist for things a project should have completed if you are considering being a contributor.