status-im
/
sourcecred
mirror of https://github.com/status-im/sourcecred.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
sourcecred/README.md

112 lines
4.8 KiB
Markdown
Raw Normal View History

Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
# [SourceCred](https://sourcecred.io)
Initial draft of the README (#1) * Initial commit of README * Fix some typos, etc * More tweaks. * More iterations on markdown, etc * Take Jay's suggestion
2018-02-04 20:04:40 +00:00
readme: replace Travis badge with CircleCI badge (#912) Summary: See #902 for context. Test Plan: Push to GitHub; observe badge in rendered README. wchargin-branch: readme-circleci-badge
2018-10-03 18:43:10 +00:00
[![Build Status](https://circleci.com/gh/sourcecred/sourcecred.svg?style=svg)](https://circleci.com/gh/sourcecred/sourcecred)
Link to https://discuss.sourcecred.io from README (#725) Adds a badge, adds a link, slight rewrite of the contributing section. Test plan: Check the links and badge works. (The badge topic count is off, we'll see if it is at least directionally correct over time.)
2018-08-30 00:51:54 +00:00
[![Discourse topics](https://img.shields.io/discourse/https/discuss.sourcecred.io/topics.svg)](discuss.sourcecred.io)
Update README to reference our Discord (#363)
2018-06-08 19:30:44 +00:00
[![Discord](https://img.shields.io/discord/453243919774253079.svg)](https://discord.gg/tsBTgc9)
Add Travis badge to README (#59)
2018-03-02 23:06:46 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
SourceCred creates reputation networks for open-source projects.
Any open-source project can create its own _cred_, which is a reputational metric showing how much credit contributors deserve for helping the project.
To compute cred, we organize a project’s contributions into a graph, whose edges connect contributions to each other and to contributors.
We then run PageRank on that graph.
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
README links to my introductory post on cred (#726) Test plan: Check that links work.
2018-08-30 02:16:57 +00:00
To learn more about SourceCred’s vision and values, please check out [our website] and our [forum].
One good forum post to start with is [A Gentle Introduction to Cred].
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
For an example of SourceCred in action, you can see SourceCred’s own [prototype cred attribution][prototype].
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
[our website]: https://sourcecred.io/
[prototype]: https://sourcecred.io/prototype/
README links to my introductory post on cred (#726) Test plan: Check that links work.
2018-08-30 02:16:57 +00:00
[A Gentle Introduction to Cred]: https://discuss.sourcecred.io/t/a-gentle-introduction-to-cred/20
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
## Current Status
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
We have a [prototype] that can generate a cred attribution based on GitHub interactions (issues, pull requests, comments, references, etc.).
We’re working on adding more information to the prototype, such as tracking modifications to individual files, source-code analysis, GitHub reactions, and more.
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
### Running the Prototype
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
If you’d like to try it out, you can run a local copy of SourceCred as follows.
First, make sure that you have the following dependencies:
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
- Install [Node] (tested on v8.x.x).
- Install [Yarn] (tested on v1.7.0).
- Create a [GitHub API token]. No special permissions are required.
Document that GNU coreutils are required (#733) Summary: Resolves #698. See the linked issue and comment for more details. Test Plan: None. wchargin-branch: document-gnu-coreutils
2018-08-30 15:58:32 +00:00
- For macOS users: Ensure that your environment provides GNU
coreutils. [See this comment for details about what, how, and
why.][macos-gnu]
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
[Node]: https://nodejs.org/en/
[Yarn]: https://yarnpkg.com/lang/en/
[GitHub API token]: https://github.com/settings/tokens
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Document that GNU coreutils are required (#733) Summary: Resolves #698. See the linked issue and comment for more details. Test Plan: None. wchargin-branch: document-gnu-coreutils
2018-08-30 15:58:32 +00:00
[macos-gnu]: https://github.com/sourcecred/sourcecred/issues/698#issuecomment-417202213
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
Then, run the following commands to clone and build SourceCred:
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
```
git clone https://github.com/sourcecred/sourcecred.git
cd sourcecred
yarn install
yarn backend
Demonstrate the GitHub token env var in the README (#556) Summary: Using the environment variable is the preferred way to interact with the CLI, simply because it’s easier for users. We should demonstrate this interface instead of the legacy flag-only version. Paired with @decentralion. wchargin-branch: readme-env-var
2018-07-28 03:59:54 +00:00
export SOURCECRED_GITHUB_TOKEN=YOUR_GITHUB_TOKEN
CLI takes repo strings as `owner/name` (#559) Test plan: ``` $ yarn backend $ node bin/sourcecred.js load sourcecred/sourcecred ```
2018-07-28 06:44:41 +00:00
node bin/sourcecred.js load REPO_OWNER/REPO_NAME
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
# this loads sourcecred data for a particular repository
minor tweak to starting instructions (#1046)
2019-01-11 00:52:08 +00:00
# it can take a few mins to run and will exit when finished
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
yarn start
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
# then navigate to localhost:8080 in your browser
Update README (#482) Rewrites the README to be a lot more concrete about what SourceCred is doing, and to give more up-to-date information overall. Test plan: The README includes a small code block with instructions for turning on a local copy of the Cred Explorer. I ran this on my machine (inside /tmp) and it worked locally.
2018-07-04 08:11:23 +00:00
```
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
For example, if you wanted to look at cred for [ipfs/js-ipfs], you could run:
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
```
Demonstrate the GitHub token env var in the README (#556) Summary: Using the environment variable is the preferred way to interact with the CLI, simply because it’s easier for users. We should demonstrate this interface instead of the legacy flag-only version. Paired with @decentralion. wchargin-branch: readme-env-var
2018-07-28 03:59:54 +00:00
$ export SOURCECRED_GITHUB_TOKEN=0000000000000000000000000000000000000000
CLI takes repo strings as `owner/name` (#559) Test plan: ``` $ yarn backend $ node bin/sourcecred.js load sourcecred/sourcecred ```
2018-07-28 06:44:41 +00:00
$ node bin/sourcecred.js load ipfs/js-ipfs
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
```
Demonstrate the GitHub token env var in the README (#556) Summary: Using the environment variable is the preferred way to interact with the CLI, simply because it’s easier for users. We should demonstrate this interface instead of the legacy flag-only version. Paired with @decentralion. wchargin-branch: readme-env-var
2018-07-28 03:59:54 +00:00
replacing the big string of zeros with your actual token.
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
[ipfs/js-ipfs]: https://github.com/ipfs/js-ipfs
Allow combining repositories at load time (#711) Summary: As a first pass toward support for analyzing whole organizations, we allow loading multiple repositories with `sourcecred load`, combining them into a single relational view and a single Git graph at load time. Test Plan: Run ``` node bin/sourcecred.js \ load \ sourcecred/example-git \ sourcecred/example-github \ sourcecred/sourcecred \ --output sourcecred/examples \ ; ``` and select `sourcecred/examples` from the web view. Filter “Repository” nodes, and note that there are three. Note that loading a single repository without `--output` still works, that loading a single repository with `--output` still works (respecting the alias name), and loading not exactly one repository without `--output` yields an appropriate error message. Note that `yarn sharness-full` still works. wchargin-branch: load-combined
2018-08-29 21:52:26 +00:00
You can also combine data from multiple repositories into a single graph.
To do so, pass multiple repositories to the `load` command, and specify an “output name” for the repository.
For instance, the invocation
```
node bin/sourcecred.js load ipfs/js-ipfs ipfs/go-ipfs --output ipfs/meta-ipfs
```
will create a graph called `ipfs/meta-ipfs` in the cred explorer, containing the combined contents of the js-ipfs and go-ipfs repositories.
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
## Early Adopters
Update the README (#124) - Give a more detailed and up-to-date vision for SourceCred - Update the discuss link to point to Spectrum rather than Slack - Wrap text
2018-04-09 05:49:54 +00:00
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
We’re looking for projects who want to be early adopters of SourceCred!
Link to https://discuss.sourcecred.io from README (#725) Adds a badge, adds a link, slight rewrite of the contributing section. Test plan: Check the links and badge works. (The badge topic count is off, we'll see if it is at least directionally correct over time.)
2018-08-30 00:51:54 +00:00
If you’re a maintainer of an open-source project and would like to start using SourceCred, please reach out to us on our [Discord] or our [forum].
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
## Contributing
We’d love to accept your contributions!
Link to https://discuss.sourcecred.io from README (#725) Adds a badge, adds a link, slight rewrite of the contributing section. Test plan: Check the links and badge works. (The badge topic count is off, we'll see if it is at least directionally correct over time.)
2018-08-30 00:51:54 +00:00
You can reach out to us by posting on our [forum], or chatting with us on [Discord].
We'd be happy to help you get started and show you around the codebase.
Please also take a look at our [contributing guide].
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
If you’re looking for a place to start, we’ve tagged some issues [Contributions Welcome].
Link to `CONTRIBUTING.md` from the README (#585) Summary: The information currently in the README is helpful but incomplete. We now have a `CONTRIBUTING.md` guide, so we can simply link to that. Test Plan: None. wchargin-branch: contributing-md-readme
2018-08-02 20:58:06 +00:00
Link to https://discuss.sourcecred.io from README (#725) Adds a badge, adds a link, slight rewrite of the contributing section. Test plan: Check the links and badge works. (The badge topic count is off, we'll see if it is at least directionally correct over time.)
2018-08-30 00:51:54 +00:00
[forum]: https://discuss.sourcecred.io
README: Adding contribution section (#518) * README: Adding contribution section * README: adding links to Prettier
2018-07-24 20:38:40 +00:00
[Discord]: https://discord.gg/tsBTgc9
Link to `CONTRIBUTING.md` from the README (#585) Summary: The information currently in the README is helpful but incomplete. We now have a `CONTRIBUTING.md` guide, so we can simply link to that. Test Plan: None. wchargin-branch: contributing-md-readme
2018-08-02 20:58:06 +00:00
[contributing guide]: https://github.com/sourcecred/sourcecred/blob/master/CONTRIBUTING.md
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
[Contributions Welcome]: https://github.com/SourceCred/SourceCred/issues?q=is%3Aopen+is%3Aissue+label%3A%22contributions+welcome%22
license: relicense under MIT + Apache-2 (#896) Summary: All contributors to SourceCred have agreed to this more permissive licensing option: - @decentralion: [link to comment][decentralion] - @wchargin: [link to comment][wchargin] - @claireandcode: [link to comment][claireandcode] [decentralion]: https://github.com/sourcecred/sourcecred/issues/812#issuecomment-420817902 [wchargin]: https://github.com/sourcecred/sourcecred/issues/812#issuecomment-420819732 [claireandcode]: https://github.com/sourcecred/sourcecred/issues/812#issuecomment-424914639 Archive link to thread: <https://archive.fo/BH2v5> Resolves #812. Test Plan: Note that the GitHub tree explorer correctly links from the README to the individual license files. wchargin-branch: license-dual-mit-apache2
2018-09-27 02:28:41 +00:00
## License
SourceCred is dual-licensed under Apache 2.0 and MIT terms:
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
* MIT License ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
Update README.md (#700) The README has been brought up to date, and many small improvements were made. See #700 for details. Test plan: Thoroughly reviewed.
2018-08-24 05:04:43 +00:00
## Acknowledgements
We’d like to thank [Protocol Labs] for funding and support of SourceCred.
We’d also like to thank the many open-source communities that produced the software that SourceCred is built on top of, such as Git and Node.
[Protocol Labs]: https://protocol.ai