<commit_before>The OCO permissions system allows setting up membership classes, and to define
the level of access a membership class has to the system.

Each member class is associated with a list of permission flags which turn
individual features on or off. These are stored as Clauses in the constitution,
which means membership class permission changes are made in the form of a
change to the constitution.

(Implementation detail: permissions are stored as boolean flags in the 
"clauses" database table; in the absence of such a permission entry for a 
particular member class the default is to _not_ grant access.)

Progress for this work is being tracked at:
http://github.com/emmapersky/one-click-orgs/issues/62

 ==============================
 = Setting up an Organisation =
 ==============================

We can pre-populate the system with a set of classes, e.g. "Director" and 
"Member", along with instructions on how to customise them.

Setting up the database via 'rake db:setup' will set up a simple organisation 
where all members are equal. (Check ./db/seeds.rb if you want to change this.)

You can customise your organisation by changing that script, or via the Rails 
console:

$ ./script/rails console
> directors = MemberClass.find_or_create_by_name('Director')
> directors.set_permission(:constitution_proposal, true)
> directors.set_permission(:membership_proposal, true)
> directors.set_permission(:freeform_proposal, true)
> directors.set_permission(:vote, true)
> members = MemberClass.find_or_create_by_name('Member')
> members.set_permission(:constitution_proposal, false)
> members.set_permission(:membership_proposal, false)
> members.set_permission(:freeform_proposal, true)
> members.set_permission(:vote, true)

 ============================
 = Migrating Member Classes =
 ============================

# TODO

 ============================
 = The Membership Lifecycle =
 ============================

There are a limited number of ways in which a member gets added:

* DONE: as the founding member who sets up the organisation
** TODO: validate form input

* DONE: an existing member creates a "New Member" proposal, this passes
** TODO: validate form input (atm empty values still result in a proposal)

* DONE: list of founding members during induction (this may get removed later)
** TODO: validate form input

DONE: Members can only change their class via proposal.
** TODO: validate form input (the comment)

 ================================
 = The Member Classes Lifecycle =
 ================================

TODO: Member classes can get added via a proposal.
* new proposal type: add member class
** UI: add Member Classes section at one_click/constitution -> new member class form (with a list of permissions)
** model: new add_member_class_proposal class
** ...I think that's it.
-> easy

TODO: Member classes can get modified via a proposal.
* new proposal type: modify member class
** UI: add Member Classes section at one_click/constitution -> modify member class form (with a list of permissions)
** model: new modify_member_class_proposal class
** ...I think that's it.
-> easy

TODO: Member classes can get deleted via a proposal.
* new proposal type: delete member class
** UI: add Member Classes section at one_click/constitution -> delete member class form (with the name of the member class that users get migrated to)
** model: new delete_member_class_proposal class
** ...I think that's it.
-> easy

 =======================
 = List of Permissions =
 =======================

Currently we can manage access to several kinds of proposals:
* :constitution_proposal -- create proposals for any kind of constitutional change
* :membership_proposal -- create proposals for adding or ejecting members, or changing their member class
* :freeform_proposal -- create freeform proposals

The permission to vote on proposals is not yet broken down by subtypes:
* :vote -- voting on proposals: constitution change, membership change, freeform proposals
* TODO :constitution_vote -- vote on a constitutional proposal
* TODO :membership_vote -- vote on a membership proposal
* TODO :freeform_vote -- vote on a freeform proposal
<commit_msg>doc updates: how to add a new permission type<commit_after>The OCO permissions system allows setting up membership classes, and to define
the level of access a membership class has to the system.

Each member class is associated with a list of permission flags which turn
individual features on or off. These are stored as Clauses in the constitution,
which means membership class permission changes are made in the form of a
change to the constitution.

(Implementation detail: permissions are stored as boolean flags in the 
"clauses" database table; in the absence of such a permission entry for a 
particular member class the default is to _not_ grant access.)

Progress for this work is being tracked at:
http://github.com/emmapersky/one-click-orgs/issues/62

 ==============================
 = Setting up an Organisation =
 ==============================

We can pre-populate the system with a set of classes, e.g. "Director" and 
"Member", along with instructions on how to customise them.

You can customise your organisation by editing the 
create_default_member_classes function in the Organisation model, or via the 
Rails console:

$ ./script/rails console
> directors = MemberClass.find_or_create_by_name('Director')
> directors.set_permission(:constitution_proposal, true)
> directors.set_permission(:membership_proposal, true)
> directors.set_permission(:freeform_proposal, true)
> directors.set_permission(:vote, true)
> members = MemberClass.find_or_create_by_name('Member')
> members.set_permission(:constitution_proposal, false)
> members.set_permission(:membership_proposal, false)
> members.set_permission(:freeform_proposal, true)
> members.set_permission(:vote, true)

 ======================
 = Adding Permissions =
 ======================

In all places where member classes get created: add your new permission
flag to all member classes and set it to an appropriate state.

Organisation model:
- in def create_default_member_classes add:
  members.set_permission(:my_new_permission, true)

In controllers:
- where applicable add:
  before_filter :require_my_new_permission
- write a private def require_my_new_permission

In models:
- where applicable add checks: 
  if current_member.has_permission(:my_new_permission)

In views:
- where applicable add checks: 
  - if current_user.has_permission(:my_new_permission)

Done.

 ============================
 = Migrating Member Classes =
 ============================

# TODO

 ============================
 = The Membership Lifecycle =
 ============================

There are a limited number of ways in which a member gets added:

* DONE: as the founding member who sets up the organisation
** TODO: validate form input

* DONE: an existing member creates a "New Member" proposal, this passes
** TODO: validate form input (atm empty values still result in a proposal)

* DONE: list of founding members during induction (this may get removed later)
** TODO: validate form input

DONE: Members can only change their class via proposal.
** TODO: validate form input (the comment)

 ================================
 = The Member Classes Lifecycle =
 ================================

TODO: Member classes can get added via a proposal.
* new proposal type: add member class
** UI: add Member Classes section at one_click/constitution -> new member class form (with a list of permissions)
** model: new add_member_class_proposal class
** ...I think that's it.
-> easy

TODO: Member classes can get modified via a proposal.
* new proposal type: modify member class
** UI: add Member Classes section at one_click/constitution -> modify member class form (with a list of permissions)
** model: new modify_member_class_proposal class
** ...I think that's it.
-> easy

TODO: Member classes can get deleted via a proposal.
* new proposal type: delete member class
** UI: add Member Classes section at one_click/constitution -> delete member class form (with the name of the member class that users get migrated to)
** model: new delete_member_class_proposal class
** ...I think that's it.
-> easy

 =======================
 = List of Permissions =
 =======================

Currently we can manage access to several kinds of proposals:
* :constitution_proposal -- create proposals for any kind of constitutional change
* :membership_proposal -- create proposals for adding or ejecting members, or changing their member class
* :freeform_proposal -- create freeform proposals

The permission to vote on proposals is not yet broken down by subtypes:
* :vote -- voting on proposals: constitution change, membership change, freeform proposals
* TODO :constitution_vote -- vote on a constitutional proposal
* TODO :membership_vote -- vote on a membership proposal
* TODO :freeform_vote -- vote on a freeform proposal

{'fraction_non_alphanumeric': 0.1288056206088993, 'fraction_numerical': 0.0004460800713728114, 'mean_word_length': 5.12987012987013, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, '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': '4469194', 'n_tokens_mistral': 2296, 'n_tokens_neox': 2194, 'n_words': 1046}