As requested by @s-ben, we map now include cred over time for all
contributions, not just contributors. Based on discussion with @Beanow,
we made it an optional field so that we can optionally filter to save
space instead.
I was initially concerned that we wouldn't be able to compute
credOverTime for non-user nodes in CredRank, which is why I left it out.
However, informed by discussions with @mZargham, I'm less concerned
because PageRank (and thus CredRank) is a linear operator on the seed
vector. So, if we want to compute the "cred over time" for individual
contributions in CredRank, we can do so by constructing time-specific
seed vectors (which flow only to activity minting cred in the specified
interval), and the sum of contributions time-scoped cred will be equal
to the non-time-scoped cred. It's good that we'll still have the epoch
nodes for users, as that will allow us to model sponsorship cred flow
dynamics.
cc @wchargin for CredRank considerations.
Test plan: Unit tests updated, `yarn test` passes.
This commit builds on the change in #1789 which made Timestamp
validation optional. Now, it is convenient to use Timestamps
consistently across the codebase. This is split out from #1788.
Test plan: `yarn test` and `git grep "timestampMs: number"`. The only
hit is within the timestamp module itself.
Currently, the Timestamp module requires that all TimestampMs types be
validated via the `fromNumber` method. However, as discussed in #1788,
this creates marginal benefit (just knowing that a TimestampMs is an
integer does not give great confidence that it's a meaningful and
correct timestamp for any use case), and creates a lot of overhead,
especially in test code. It makes adopting the TimestampMs type across
the codebase an arduous and mostly thankless task that would involve
re-writing dozens or hundreds of test instances to add zero actual
safety.
Therefore, I've made the type non-opaque, and renamed `fromNumber` to
`validate`. I then changed existing test code to not use the validator,
since we don't need any manual validation of our test cases, and `123`
is not a meaningful timestamp in any case :)
Test plan: `yarn test`
This commit updates the alias module so that we may convert node
addresses into aliases. Naturally, the node address needs to be some
kind of user node address that is known to the aliasing scheme.
It's a big in-elegant that this creates a "hidden" integration point for
plugins, where plugins creating new user node types should add hardcoded
logic into the identity plugin's alias system. However, it is a
convenience and we currently use this system, so I'm just going to add
this functionality for now, and think about how the alias system should
work long term (or whether we should phase it out) for another
discussion.
This is needed for #1773.
I have `toAlias` return `null` when the address doesn't correspond to a
known aliasing scheme, rather than erroring. I think erroring would be
too harsh, given that it's quite possible that the user has loaded
third-party plugins that haven't registered aliasing schemes upstream
with us. In that case, the application should make a best effort attempt
to proceed without an alias (e.g. fallback to the full address), for
robustness.
Test plan: Unit tests included; `yarn test` passes.
* Add grain allocation module
This adds the `grain/allocation.js` module, which contains logic for computing "grain allocations" based on cred scores.
The resultant Allocation type contains the receipts (who gets how much Grain) and the
strategy informing the payout. We can then include these directly into the ledger
to keep a record of the grain balances.
The code is pretty well tested, hitting a number of potential edge cases in the
distribution logic.
Test plan: Inspect attached unit tests, verify CI passes.
Paired with @decentralion
* Rename "Lifetime" distribution strategy to "Balanced" distribution strategy
Balanced more accurately describes what the strategy is doing since its optimizing
to reduce the "imbalance" of cred scores with total grain earnings.
Test Plan: grep "lifetime" to ensure its not used to refer to a distribution strategy
* Refactor strategy specific logic in distribution function
Cleans ups the distribution function by moving all the logic for transforming data and handling errors
into the respective functions (computeImmediateReceipts and computeBalancedReceipts). Also added a test
to ensure error is thrown on an unsupported strategy with an empty credHistory.
Test Plan: Ensure unit tests pass
* Return an empty distribution if budget is zero
Adds a check for when budget === ZERO to return an empty array of receipts to prevent
having receipts with zero grain
Test Plan: Ensure unit tests pass
* Rename earnings to lifetimeEarningsMap
This makes it more descriptive and explicit that the parameter is supposed to be
the lifetime earnings of each contributor, vs "earnings" which could mean many things
Test Plan: Grep "earnings" (case sensitive) to ensure its no longer used in places
where its representing lifetime earnings of all contributors
* Rename distribution to createGrainDistribution
Also renamed the related types / vars from "Distribution" to "GrainDistribution".
This makes it more descriptive and explicit that it is a distribution of Grain,
not a probability distribution or any other distribution. Prevents potential naming
conflicts / confusion with the core/algorithm/distribution module.
Test Plan: Grep "distribution" to ensure that the grain related code always uses
"GrainDistribution"
* Rename GrainDistribution to GrainAllocation
This simplifies the scope of the grain distribution module
to focus purely on the calculations for the Immediate and
Balanced allocation strategies instead of trying to solve
for the actual "ledger of events". The time-filtering has
been removed with the responsibility being delegated to the
caller of the functions. The actual "GrainDistributed" events
can contain the timestamp and an array of "GrainAllocation"s.
Test Plan: Grep "distribution" to ensure its no longer used
in this PR when referring to a GrainAllocation. Also ensure
all the unit tests pass.
* Move "budget" field from Strategy to GrainAllocation
It feels more appropriate for the budget to be a property
of a GrainAllocation since we are allocating that amount of
grain based on a certain strategy. The strategy type is just
meant to describe how the grain was allocated, not how much
grain was allocated. Its also more appropriate since a "distribution"
will have an array of GrainAllocation's instead of GrainAllocation
having an array of strategies, each with different amounts
of grain budget.
Test Plan: Ensure there are no type errors and that Unit tests are passing
* Simplify test cases for GrainAllocation strategies
There was a lot of duplicated test code for the different
allocation strategies, this consolidates it by using describe.each
to run the same test suites on both strategies.
Test Plan: Ensure that unit tests pass and that both strategies
have test coverage for the common test cases
* Rename "lifetimeEarningsMap" to "lifetimeGrainAllocation" and "credMap" to "immediate/lifetimeCredMap"
Changes the naming of some params / variables to be more
descriptive / accurate.
Test Plan: grep "lifetimeEarnings" to ensure its no longer used anywhere
* Improve clarity for balanced allocation test cases
Adds comments to explain the reasoning behind expected receipts
and update calculations to consistently use the "BUDGET"
variable
Test Plan: Ensure CI tests pass
This command is basically a fork of `cli/scores`, except it outputs the
format described in #1773. I started by copying cli/scores and
sharness/test_cli_scores.t, and made appropraite modifications.
You can check out the example-github-output.json to get a feel for the
new format. I also added a compat header in `analysis/output.js`, and
made the necessary adjustments to the CLI harness.
Test plan: The sharness test runs the real command and saves output in
its success case, looking at that JSON is sufficient. I also manually
ran it on the @sourcecred project.
This commit builds on #1781, adding the logic for computing the first
output format from TimelineCred. See #1773 for context.
Test plan:
The logic is simple, but has a couple interesting edge cases. I've added
unit tests to cover them. `yarn test` passes.
This includes packages that can be upgraded without making changes.
* Chore: minor version upgrades
* Chore: upgrade fs-extra
* Chore: upgrade chalk
* Chore: upgrade jest, babel-jest
Closes#1712Closes#1734
As explored in #1773, this commit adds some output data formats that we
can use to enable data analysis of cred instances, along with powering
new UIs. I've included three output formats in order of increasing
complexity, with the intention that we can ship the simpler output
formats quickly, and then enhance with more information to power better
analyses.
I've tried to ensure forward-compatibility with CredRank, so that we can
migrate to CredRank without needing to make major changes to this API.
I may want to include type information in the output format as well.
Test plan: Human review and consideration. `yarn test` passes.
Thanks to @s-ben and @Beanow for discussion, review, and inspiration.
This adds a bash script that fetches data from our test
Discord instance. We will be able to test against this
data and easily update the data if Discord's api changes.
Test plan:
After running bash script, inspected snapshot files
and verified that the data appears reasonable.
Verified that the check for `jq` and `SOURCECRED_DISCORD_TOKEN` both
fail and exit if `jq` isn't installed or the Discord bot token
hasn't been set.
As of this commit the plugin should fully support EdgeSpec. Meaning the
entries are included in the Graph and Cred computations.
As the champions field does support URLs but not NodeEntry from an
EdgeSpec, we're separating the URL handler from the EdgeSpec handler.
Summary:
This replaces the logo with another SVG document that looks (roughly)
the same but is implemented more cleanly. In particular, the segments of
rays now overlap properly and so are not subject to aliasing, which also
makes it easier to create color variations (e.g., for monochrome).
I would usually optimize this further with SVGO, but this document
appears to reveal a bug in SVGO’s “Round/rewrite paths” optimization
that causes the document to render correctly in Chrome and Firefox but
incorrectly in `rsvg-convert` and Inkscape, so I’m stopping here.
Test Plan:
An animation shows the structure of the new SVG:
![SVG structure animation][gif]
[gif]: https://user-images.githubusercontent.com/4317806/78756263-5da8f880-792f-11ea-9fd1-8e1380e3c530.gif
wchargin-branch: logo-overlapping-paths
Removes extraneous whitespace in comments in the Discord Plugin.
Test Plan:
Grepping `/*` in the `src/plugins/discord` directory should show
6 instances of this comment style, all of which should have no
whitespace after the final line of content.
`yarn test` passes.
Because the `Initiative` type now supports `EdgeSpec`, we're no longer
discarding entries when converting between `InitiativeFile` and
`Initiative`.
To make this commit smaller and easier to review, we're not yet adding
support to add `NodeEntry` to the graph though, instead
`createWeightedGraph` ignores the entries for now.
An additional change here is we're allowing more keys to be omitted in
the JSON format. This is both intuitive for data entry, and safer in
terms of Flow types (as JSON.parse returns any).
The test examples now cover a v0.1.0 (initiative-A), v0.2.0 with just
URLs (initiative-B) and one with just entries (initiative-C).
To make this commit smaller and easier to review, we're not yet adding
`EdgeSpec` to the `Initiative` type and will ignore the entries when
converting from `InitiativeFile` to `Initiative`.
Defines the NodeAddress format we want to use for a NodeEntry.
Because we want to use the parent InitiativeId as parts of the address,
we'll need to read the underlying string[], changing the opaque type.
This commit modifies the resolveAlias function in the identity plugin's
alias module so that it now allows you to convert sourcecred identity
aliases (e.g. "sourcecred/user") back into NodeAddresses. This will be
necessary so that we can convert our ad-hoc distributions and transfers
(which use aliases, including SourceCred identity aliases) into the more
robust formats for the productionized grain ledger, which use full node
addresses.
I did a slight refactor on the identity module to expose a method for
constructing the address without the rest of the node.
Test plan: `yarn test`
Summary:
Version 5.0.0 of `better-sqlite3` redesigned the `Database.transaction`
method to do exactly what we want, obviating the need for our custom
helper function and tests. It’s actually more flexible: it allows the
transaction function to take arguments, and allows nested transactions.
Test Plan:
All tests pass as written. If this patch is instead made by changing the
implementation of `_inTransaction` to `return db.transaction(fn)()`,
most tests still pass, excepting only some tests about the behavior of
`_inTransaction` itself around transaction nesting and manual rollbacks;
those behavior changes are acceptable, especially given that they’re not
exercised in the code under test.
wchargin-branch: mirror-builtin-transaction
Summary:
I first wrote these type definitions for v4.x.x. The library API has
changed since then. This patch updates the type definitions to match the
current API as of the v7.0.0 release:
<https://github.com/JoshuaWise/better-sqlite3/blob/v7.0.0/docs/api.md>
There are breaking changes, but none among functions that we use. On the
other hand, there are new features that will be useful to us.
Test Plan:
Running `yarn flow` still passes. There may be some errors among typing
of functions that we don’t actually use (particularly `aggregate`, which
is more complicated than the others). If so, we can cross those bridges
when we come to them.
wchargin-branch: flow-better-sqlite3-v7-api
Summary:
In `_findOutdated`, we bound a query parameter that was not used by the
query. This is entirely harmless, but should still be fixed.
Test Plan:
That unit tests continue to pass suffices.
wchargin-branch: mirror-findoutdated-superfluous-param
Summary:
This fixes a bug introduced in #1665, where we added a `typenames`
clause to the query plan but didn’t update the termination checking
accordingly. As a result, query plans with only `typenames` left to
update would not execute, so `extract` would fail with a `NOT NULL`
constraint violation because not all transitively needed objects had
been fetched.
Databases created before this change are still valid. Re-running the
problematic `sourcecred load` command should successfully update the
cache and proceed.
Fixes#1762.
Test Plan:
Regression test added; `aracred/ideas` and `aracred/aracred-template`
both load successfully now.
wchargin-branch: mirror-typenames-only-plan
Adds a new NodeType for each NodeEntryField. Allowing multipliers to be
set per field.
Since the "contributes to" edge is very generic and created a naming
conflict, this includes a slightly awkward "contributes to entry" addition.
Including "entry" to differentiate from the existing edge type.
The edge weights for this loosely follow the current edge weight rationale.
When we've merged enough functionality to do in-browser testing of different
weights with an example scenario, I think we should revisit them.
This type will replace the current `$ReadOnlyArray<URL>` on the Initiative
fields to support NodeEntry arrays as well. Like with the NodeEntryJson
they will have a manual-entry convenience flavor and an internally
normalized one.
The normalization function aims to throw errors that help users notice any
input mistakes.
This is where most flexibility when hand-writing JSON files is expected
to come from. As it makes few assumptions about the formatting but the
internal normalized type is still consistent.
This is the generalized type that allows us to define contributions to an
Initiative from the same JSON file as the Initiative. See #1739.
The types distinguish between what a user is expected to enter and what
this is internally normalized to. The normalization logic is implemented
in a follow-up PR.
Often we can use representations like Set to avoid duplicates in the first
place. However when duplicates are not allowed in some kind of user input
we may want to present them with a useful error message.
This util will find the duplicate elements, so they can be highlighted
in an error.
Add a numerically-naive method for calculating the floating point ratio
between grain values, as it is needed in #1743.
Following discussion in [this review], we hope that @wchargin will
re-write this method later to have better precision.
Test plan: Attached unit tests should pass.
[this review]: https://github.com/sourcecred/sourcecred/pull/1715#discussion_r396909459
Paired with @hammadj
Adds a class to persist a local mirror of data from a Discord Guild.
Implements create and read functionality.
Adds a function to `models` which converts an Emoji string-reference
into an Emoji object.
Test plan:
Unit tests added.
Paired with: @beanow
By adding information about configuration and what identity contractions
do, it provides more reference for instance maintainers and community
members to understand the plugin.
Includes rephrasing and feedback from @s-ben and @vsoch.
Closes#1725
In PR #1746 we've added `src/util/timestamp.js`. This commit replaces the
plugin's internal opaque string and number types with well tested types
and conversion functions.
As we're looking to add more features to InitiativeFile, the single source
file would grow large. Anticipating this we're splitting one type and it's
related functions off into a new file.
* Add a README.md for the GitHub plugin
This mostly documents at a conceputal level that would be useful for
users; it's not trying to document it for contributors to the GitHub
plugin, although that could be useful as a followup.
Sending this out for initial review, although arguably we should merge
it to sourcecred/docs rather than directly alongside the code. I welcome
feedback on content, structure, and location.
Test plan: No tests, just review.
* Address review feedback
* Address @s-ben's review feedback
The URL type used by Initiatives was added before reference detection was
fully fleshed out. Since we'll use this reference detection, we'll use
it's URL type as well.
Previously we intended to use Discourse as a source of Initiatives.
Since we're not taking this approach anymore, we're removing the
related features here.
We have a convention of using TimestampMs as our default representation.
However TimestampISO has the benefit of being human readable / writable,
so it's used for serialization and display as well.
We'll validate types at runtime, as there's a fair chance we'll use these
functions to parse data that came from a Flow `any` type (like JSON).
Fixes#1653
This is a fairly simple helper function that allows transforming a Map into an Array using a provided transformer function. It's really an alias for `Array.from(map.entries()).map(f)`, which is nice because that invocation is somewhat tedious to write.
Test plan: The method is very simple; we've added some correspondingly simple test. Also, grepping for `Array\.from(.*\.entries())\.map` should return no hits (i.e. we've converted existing usage).
Paired with @decentralion
Test Plan: grep for global BigInt and make sure there's no longer
instances in code files now that we added it to central ESLint Config
Paired with @decentralion
This commit adds two math helpers to the `grain` module:
`multiplyFloat` has a canonical way to multiply a grain amount by a
floating point number, which is useful e.g. if we need to multiply grain
amounts by cred ratios. For now, we have a naive approach which coerces
the grain into a float, does float multiplication, and then converts
back to grain.
This is imprecise, but in testing (see [notebook]) the absolute error
amounts are very small, i.e. in the atto-grain to femto-grain range.
Because we will be using this in conjunction with payout strategies that
implement explicit payment-error-correction over time (i.e. we calculate
who has been historically under-paid and give them more reward), these
insignificant errors will tend to disappear rather than accumulate over
time.
`fromFloat` is a helper method for creating a grain balance directly
from a float. It's basically an alias for `multiply(ONE, float)` and
is useful for test code.
Test plan: Unit tests included (and re-factored to use the new helpers).
See attached notebook for some exploration of error values.
[notebook]: https://observablehq.com/@decentralion/grain-arithmetic
"This rule is aimed at flagging variables that are declared using let
keyword, but never reassigned after the initial assignment."
https://eslint.org/docs/rules/prefer-const
This is a rule that helps you spot mistakes while writing code with a
let statement. When thinking that you will need to reassign it, eslint
will point out you're not actually doing so.
This could be because you've forgotten something, assigned the wrong
variable, or no longer need to reassign.
Removes `roles` as a property of `GuildMember` because the use
case is not clear at this point in time.
Test Plan: Yarn Test passes. `git grep -i "roles"` also returns an
empty result.
Summary:
This commit introduces an `ignoreRevsFile` for use with Git blame. See
the header of the new file for details.
Test Plan:
Run `git blame -L183,183 config/test.js`. Before this change, note that
it blames to the reformatting commit. After this change, and after
configuring `git config blame.ignoreRevsFile .git-blame-ignore-revs`,
note that it blames to the last real change.
wchargin-branch: prettier-2.0.1-unblame
This is based on notes taken during exploring of the API and building
the hackathon prototype. As the production-ready version is being built
right now, they seem like useful notes to keep on hand.
Though we don't return any value, we should wait till we've completed
the file I/O. This likely caused the flake from #1655. As we didn't
await the write, it caused a race condition where we tried to read first.
Fixes#1655
Adds a Fetcher class that takes fetch options and fetches against
the correct endpoints, returning re-formatted request data
and pagination info.
Adds a models.js file that defines Discord types.
Test Plan:
Unit tests added for fetcher class and helper functions in
models.js file.
Paired with @Beanow
Dandelion Mané
Hammad Jutt
Robin van Boven
Brian Litwin
William Chargin
greenkeeper[bot]
