invitation_limit setting is not clearly defined in doc

[TheEricMiller]

After days and days of tinkering and testing to get this to work the way I need, I found some very important things that were not discussed about INVITATION_LIMIT functionality in the documentation and believe they should be added or discussed. Or at least wiki? (not familiar with adding to that) If marked as addressed in issues this might be impossible for other to find.

*Suggested Change / Idea: use '-1' in the invitation_limit column and corresponding code to designate unlimited send capability.* This would allow more flexibility for important scenarios described below...

IMPORTANT:

1. default limit MUST be set and can NOT be 'nil', CHANGE: /config/initializers/devise.rb >>>

# Number of invitations users can send.
  # If invitation_limit is nil, users can send unlimited invitations.
  # If invitation_limit is 0, users can't send invitations.
  # If invitation_limit n > 0, users can send n invitations.
  # Default: nil
config.invitation_limit = 0 

1. you MUST RESTART your rails server for the default limit change to go in effect
2. the new invited user is held in the db with 'null' in the invitation_limit column until they accept invitation, set password, create their account ANNNDDDD only AFTER they send their first invitation themselves will the invitation_limit column be updated to the config settings of the DEFAULT - 1
3. when invitation_limit = 1 ... once the user sends their last invite the invitation_limit column will = 0 (can not send invites)

PRO TIP:

If you want to disallow general new users the ability to invite but assign and allow specific people on your admin / sales team the ability durring the first month (or period of time) of your beta then I'd recommend this...

Set config default to '0' and manually change invitation_limit for your admins to a very very high number say, '9999'. This also allows you to 'hand out' invitations to loyal & influential users on your site as rewards and you to help mold your community with the right active users. Just update those good boys & girls invitation_limit column to your decided # and they will get the assigned amount of invites and it will decrement properly for everyone.

NOTES:

If default = nil,

• auto created/assigned users CAN send UNLIMITED invitations
• manually assigning/changing the invitation_limit in db will show the stored number but will NOT decrement when the user sends an invitation

If default = 0,

• auto created/assigned users users CAN NOT send invitations.
• manually assigning users with N will be able to send that amount of invitations and the system will decrement their remaining total properly
• assigning users with 'nil'/null (NOT RECOMMENDED) in the db will NOT give them unlimited invite capability, the system will see them as new users that have not sent their first invite and will relate them to the default setting, which being 0 means they can not send invitations

If default = n,

• auto created/assigned users users CAN send N number of invitations.
• manually assigning users with N will be able to send that amount of invitations and the system will decrement their remaining total properly
• assigning users with 'nil'/null (NOT RECOMMENDED) in the db will NOT give them unlimited invite capability, the system will see them as new users that have not sent their first invite and will relate them to the default setting, which being 0 means they can not send invitations

[scambra]

Invitation_limit can be nil, I can't see why you need -1

[scambra]

1. you MUST RESTART your rails server for the default limit change to go in effect

Every change in rails needs restarting in production. Every change in an initializer in rails needs restarting in development. It's not something new neither something related to devise invitable, and devise options have the same behaviour.

1. the new invited user is held in the db with 'null' in the invitation_limit column until they accept invitation, set password, create their account ANNNDDDD only AFTER they send their first invitation themselves will the invitation_limit column be updated to the config settings of the DEFAULT - 1

Do you think is it something to put in README? It's internal behaviour, you can check with has_invitations_left? Maybe in a wiki page can be explained, but I think is not necessary.

Really, when is nil, there is no invitation_limit, changing invitation_limit in users has no effect because you have disabled invitation_limit globally, so invitation_limit will never be decremented. I think it doesn't need explanation, if you don't enable invitation_limit you shouldn't set invitation_limit, if you want to use invitation_limit enable it (set a number, not nil)