diff --git a/docs/fcas/creation_workflow.rst b/docs/fcas/creation_workflow.rst index f526451..dedd0b8 100644 --- a/docs/fcas/creation_workflow.rst +++ b/docs/fcas/creation_workflow.rst @@ -12,14 +12,15 @@ repository is located at How does it work? ---- -There are essentially two functional units in the project - the ``namelist`` that -lets the service runner fetch the usernames from the FASJSON service on a file -and the ``actvlist`` that checks the activity for the names present in the -aforementioned file on Datagrepper. These are run as automated cronjobs to be -run once every after a certain period of time to obtain both an updated list -of usernames as well as an updated count of active users. The functioning of -the service is governed by a configuration file that can be edited to suit the -requirements of those running the service. +The project consists of two main functional units: the ``namelist`` unit and +the ``actvlist`` unit. The ``namelist`` unit facilitates the retrieval of +usernames from the FASJSON service by the service runner, while the +``actvlist`` unit verifies the activity status of the names listed in the +aforementioned file through Datagrepper. Both units are executed as automated +cronjobs, scheduled to run at specific intervals. This ensures that the service +maintains an up-to-date list of usernames and a count of active users. The +service's behavior is controlled by a configurable file, allowing +administrators to tailor it according to their specific needs. **Usage** :: @@ -34,7 +35,7 @@ requirements of those running the service. namelist Fetch a list of usernames on the Fedora Account System Configuration file -^^^^ +---- The sample configuration file can be found `here `_ that can be @@ -62,7 +63,7 @@ scope. These variables are intended only for developers. 1. ``dfltsize`` (Default - 1000) - Size of iterable pages for all entities present in the FASJSON service The ``namelist`` unit -^^^^ +---- The service unit takes up the configuration variables like ``username`` and ``password`` for the user to masquerade as while probing into the FASJSON @@ -100,7 +101,7 @@ workflow on GitHub Actions is, however, 6 hours and that might, in some cases, lead to timeouts and incomplete runs. The ``actvlist`` unit -^^^^ +--- The service unit takes up the configuration variables like ``listlink`` for locating the file containing the list of all users registered on Fedora diff --git a/docs/fcas/solution_probntec.rst b/docs/fcas/solution_probntec.rst index d63ff94..00afde3 100644 --- a/docs/fcas/solution_probntec.rst +++ b/docs/fcas/solution_probntec.rst @@ -3,55 +3,60 @@ Conundrum of Tracking of Non-Technical Contributions ==== -As contributions that involve interacting with services are the only ones that -publish a message on the -`Fedora Messaging `_ bus, they are -the only ones that get tracked. These services predominantly facilitate for -technical contributions alone and hence, it becomes increasingly difficult to -track non-technical contributions. Owing to the wide range of creating non -technical contributions and a similarly huge number of subjective methods to -keep track of those - it is comparatively difficult to come up with an -objective method of describing them. What might look like a contribution to one -might not look like a contribution to someone else and therefore, the service -would not be able to reliably track non-technical contributions. +Problem statement +---- -One of the workarounds that could help solving this problem is by creating -badges on the -`Fedora Badges `_ -platform for each type of non-technical contribution. This cannot be a -solution as this method scales incredibly poorly as the members go on adding -new badges of the manually-awarded kind for tracking each type of non-technical -contributions. This could potentially lead to situations where there are -thousands of badges pertaining to a type of non-technical contribution but with -handful of awardees per badge. Going against the norm of having "subject" -usernames as owners of contribution activities, using Fedora Badges to track -contributions would lead to treating both "subject" usernames (cause of the -message publication event) and "object" usernames (involved in the said -contribution activity) to own a contribution activity. +Interactions with services are the sole means by which messages are published +on the `Fedora Messaging `_ bus, +resulting in their exclusive tracking. These services primarily cater to +technical contributions, thus posing a challenge in monitoring non-technical +contributions. Given the diverse nature of such contributions and the +subjective approaches employed to track them, devising an objective method to +describe them becomes notably arduous. What may be perceived as a contribution +by one individual may not be considered as such by another, thereby undermining +the service's ability to consistently track non-technical contributions. -How? Assuming a contribution event where a "Member X" (who has the access to -award a certain "Badge A" to members who do "Task B") awards a "Badge A" to -"Member Y". As this was a non-technical contribution and because this could not -be automatically tracked by the Fedora Badges' Message Consumer entity - the -event of "Member Y" performing "Task B" could not be reliably and automatically -tracked. The event of awarding the badge essentially confirms two contribution -activities - the first one being "Member Y" performing "Task B" and the second -one being "Member X" awarding the "Member Y" with "Badge A". In the first -contribution activity, the "Member Y" owns the contribution but they are -dependent on "Member X" to award them the badge to have their contribution -tracked. The activity of awarding the badge itself is a contribution so in the -second activity, the "Member X" owns the contribution. +One potential workaround to address this issue involves implementing badges on +the `Fedora Badges `_ +platform for various non-technical contributions. However, this approach +suffers from severe scalability issues when new badges need to be added +manually for each type of non-technical contribution. Consequently, it could +result in a scenario where there are thousands of badges associated with a +specific type of non-technical contribution, but only a few individuals +receiving each badge. Moreover, deviating from the standard practice of +assigning "subject" usernames as owners of contribution activities, adopting +Fedora Badges for contribution tracking would require both "subject" usernames +(the cause of the message publication event) and "object" usernames (involved +in the contribution activity) to possess ownership of a contribution activity. -This should be used as an absolute "last ditch effort" to track non-technical -contributions of the kind that do not automatically publish a message on the -Fedora Messaging bus when they take place. As the badges cannot be tightly -associated with the contribution activity itself and the fact that the way of -tracking those are manual in nature, they are very susceptible to be left -untracked (due to reasons like the "contribution owner" forgetting to claim -a badge when they made the "contribution activity" or the "badge felicitator" -being unavailable when being reached out causing delays in tracking of the -said activity) or to be tracked unfairly (due to reasons like the "badge -felicitator" awarding a certain badge to their friends who might not have done -the said "contribution activity" or random members claiming the badge from the -associated link in bad faith). In the larger scheme of things - this will end -greatly skewing the contributor statistics for the worse. +In the context of a contribution event, let us consider a scenario involving +"Member X," who possesses the authority to bestow "Badge A" upon individuals +who successfully complete "Task B." In this case, "Member X" awards "Badge A" to +"Member Y." However, due to the non-technical nature of this contribution, the +Fedora Badges' Message Consumer entity fails to automatically track the +occurrence of "Member Y" performing "Task B" with reliability. The act of +awarding the badge serves as confirmation for two distinct contribution +activities. The first activity involves "Member Y" carrying out "Task B," while +the second activity entails "Member X" granting "Badge A" to "Member Y." In +essence, "Member Y" is responsible for the primary contribution, but they +depend on "Member X" to receive the badge for their contribution to be +accurately recorded. On the other hand, the act of awarding the badge itself +constitutes a separate contribution, making "Member X" the owner of this +secondary activity. + +Probable workaround +---- + +This method should only be employed as a final recourse for monitoring +non-technical contributions that do not automatically generate a message on +the Fedora Messaging bus upon occurrence. Since the badges cannot be closely +linked to the contribution activity itself and the tracking process is manual +in nature, they are highly susceptible to being left untracked. This can happen +if the contribution owner forgets to claim a badge when they perform the +contribution activity, or if the badge facilitator is unavailable and causes +delays in tracking the activity. Additionally, there is a risk of unfair +tracking, such as the badge facilitator granting a specific badge to their +friends who may not have actually completed the corresponding contribution +activity, or random individuals claiming the badge through the associated link +in bad faith. In the broader context, this will significantly skew the +contributor statistics in a negative manner. diff --git a/docs/initiatives.rst b/docs/initiatives.rst index bd36be5..1a0954f 100644 --- a/docs/initiatives.rst +++ b/docs/initiatives.rst @@ -9,8 +9,6 @@ Drafts .. toctree:: :maxdepth: 1 - fcas/index - Completed review ---------------- .. toctree:: @@ -26,6 +24,7 @@ Completed review github2fedmsg/index badges/index fmn/index + fcas/index Implemented -----------