Simplify Threads app data model

[brylie]

The threads app intends to help people discuss topics. Currently, the threads data model consists of several entities:

• Thread - the container for threaded discussions
• Fact - something irrefutable, established through empirical evidence?
• Civi - an idea or proposal
• Response - a response to the Civi
• Rebuttal - disagree with or contradict a Response
• Activity - used to vote on something (Civi?, Thread?, Account?)
  • ActivityManager - returns a list of related "votes"
• Rationale - used to justify an idea (i.e., a Civi?)

Proposed changes

Clarify purpose of Threads

Since threads seem to be the foundation for discussions, make the purpose of the Thread model very clear to developers and users:

• add a docstring to the code
• UI text such as help_text

Replace the Civi model with Idea

The Civi model would seem to be at the heart of this project but is arguably just a way to express an idea for discussion and support. The discussions are the heart of CiviWiki.

Since the term Civi isn't significant, we want to use meaningful names for things, we should rename the Civi model to something that conveys its purpose. For example, the word Idea is relatively common and generic in that it doesn't imply correctness, goodness, or other similar qualities. Instead, ideas open the way for discussion and refinement.

The Idea model would preserve almost the same properties as Civi, with a refinement to the voting mechanism described below.

Simplify and harmonize voting

The Activity model handles voting.

Our voting process currently

• allows five types of vote (i.e. +2, +1, 0, -1, -2)
• contains nearly 100 lines of branching, semi-documented code
• is implemented differently for Civi and Response objects
• is modeled under the confusing name of Activity

The following simplifications would make the project easier to maintain

• only allow up/down vote ("0" would be no vote, a.k.a "abstain")
• rename Activity model to Vote
• use IntegerField for vote with min/max value of -1 and 1 up/down
  • using proper data type here to make calculation code more clean and performant (i.e. we would just sum the votes)
  • remove superfluous helper methods
• add IdeaVote and ResponseVote models
  • inherit from the Vote model
  • add FK field to respective model IdeaVote.idea and ResponseVote.response
• Add vote aggregation fields to Idea and Response models
  • vote_count_positive, vote_count_negative, score

Remove Fact model

The Fact model intends to give some empirical grounding to CiviWiki discussions.

Despite the wishes of Western rationality, facts remain an elusive abstraction. The idea of "empirical fact" begs more questions than the answers given, such as

• who determines the facts?
• when does a fact become fact? (post facto by definition)
• what do we do with facts that aren't factual?

Since CiviWiki isn't a judge of facts but facilitates discourse, it would be better to help people clarify their viewpoints and sources of information rather than appealing to some authority.

Add Reference model

Citations help clarify the sources of knowledge and opinion that are salient to the discussion. Thus, we can replace the notion of Fact with a more useful ability to add References to one's statements.

The Reference model would share a relationship with Response. The cardinality of the relationship isn't particularly important initially, so that we can allow for redundant references.

Similarly, we probably don't need to adhere to any citation format, although collecting structured data for references can support formatted citations, create URLs, and detect related ideas.

Example Reference model

Reference

• title: short title
• url: optional link to external resource

Supporting references might open up a rabbit hole of ways to cite references, such as books, magazines, etc. However, we can keep things simple for starters or perhaps use an existing package like django-citations.

Allow Responses to Civis and Responses

Currently, Responses can only be made to Civis. Allowing people to respond to Responses would foster discussion and perhaps healthy debate.

Remove Rebuttal model

The Rebuttal model implies a level of formality that CiviWiki discussions won't likely attain. Rebuttal also adds unnecessary complexity to our data model. In effect, any Response can be a rebuttal. Furthermore, responses can include rebuttals, affirmations, asides, anecdotes, and other common aspects in discussions. So let's dispense with the formality a bit and focus on promoting civil conversations.

Remove Rationale model, add rationale field to civi

The Rationale model adds a bit of unnecessary complexity to our data model and would serve better as a field on the Idea model. In addition, the Rationale model seems to have a half-baked voting mechanism. The majority of Rationale fields are already present on the hypothetical Idea model (currently Civi), which also includes voting.

Remove ActivityManager

The ActivityManager, while confusingly named, contains only one method to return related votes. This method can be implemented by a standard Django foreign key with related_name attribute, thus dispensing with the model manager.

So, the idea would be that IdeaVote and ResponseVote models would each have a foreign-key relationship to the Vote model with a related_name="votes" or something similar.

[brylie]

Of course, not all of the proposed changes would be made at once. An example roadmap might be as follows

• Remove Fact model
• Add docstring and help texts to Thread model
• Remove Rebuttal model
• Remove Rationale model
• Add rationale field to Civi model
• Rename Activity model to Vote
• Make Vote model abstract and use IntegerField for vote with min/max value of -1 and 1 up/down
• Add CiviVote and ResponseVote models with relevant FK fields
• Remove ActivityManager now obsoleted by CiviVote and ResponseVote FK related_name
• Add vote aggregation fields to Idea and Response models
  • vote_count_positive, vote_count_negative, vote_sum
• Allow responses to Civi and Response items

[AbhijithGanesh]

Sure

[gorkemarslan]

@brylie, how can I help with these changes?

One thing worth noticing, these changes should also be compatible with the frontend. We've recently made the backend clearer and pretty understandable but we have not spent great effort in the front end yet. Unfortunately, our front end is not easy to follow. It would be good if we accelerate the process of changing from Backbone.js to Django templates, discussed in issue #1129. Then we won't get lost in the front end when we apply the changes you mentioned above. Alternatively, we can start changing the backend and creating new Django templates without removing current frontend files. When a web page is ready, we can replace the relevant frontend page with this page. So, changing backend and converting to Django templates can be at the same time.

[brylie]

Since we are deprecating the front-end Backbone code, I would like to use our scarce development resources to create Django templates and simplify our data model.

[gorkemarslan]

Hey @brylie,

@AbhijithGanesh and I are eager to spend more time on the project. When you have time, could you please specify the roadmap we, as the contributors of the project, need to follow? Then we can start working on the project again. We just gave a small break. 😉

Time to get back to the open-source. :) If you need help with other projects, you can also mention them.

[brylie]

Thanks, @gorkemarslan! Right now, the major task blocking this project from moving forward is #1129

Essentially, we need to restructure those Backbone templates into Django template partials or one monolithic template (for each view). Then, we need to fix the underlying view to ensure the context data is correct.

Once we have removed the Backbone dependency, this project can move forward with new features and enhancements :-)

[brylie]

Alternatively, we can start changing the backend and creating new Django templates without removing current frontend files

This sounds like a good approach, to start the frontend templates from scratch rather than sifting through the existing Backbone/JS. Once we have created alternative templates that provide basic functionality, we can remove the Backbone code.