From 100578c536a3afab39fb6803d28913d12eac29c5 Mon Sep 17 00:00:00 2001 From: Jamie Wong Date: Mon, 20 Aug 2018 09:42:44 -0700 Subject: [PATCH] Add contributor guidelines & documentation (#144) Fixes #4 --- CODE_OF_CONDUCT.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 70 ++++++++++++++++++++++++++++++++++++++++++++ src/README.md | 13 +++++++++ 3 files changed, 156 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 src/README.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..055b243 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct: + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project +and our community a harassment-free experience for everyone, regardless of +age, body size, disability, ethnicity, gender identity and expression, level +of experience, nationality, personal appearance, race, religion, or sexual +identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of +acceptable behavior and are expected to take appropriate and fair corrective +action in response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an +appointed representative at an online or offline event. Representation of a +project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting +[jamie.lf.wong@gmail.com](mailto:jamie.lf.wong@gmail.com). All complaints +will be reviewed and investigated and will result in a response that is +deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an +incident. Further details of specific enforcement policies may be posted +separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor-Covenant][homepage], +version 1.4, available at +[https://contributor-covenant.org/version/1/4][version] + +[homepage]: https://contributor-covenant.org +[version]: https://contributor-covenant.org/version/1/4/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2b40932 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,70 @@ +# Contributing to speedscope + +Hi! This is a short guide & set of guidelines for contributing to speedscope. +Contributors of all skill levels are welcome to submit pull requests. + +This project adheres to the Contributor Covenant [code of conduct](./CODE_OF_CONDUCT.md). +All contributors are expected to uphold this code of conduct. + +## Setting up for development + +To start running speedscope locally, run the following: + + git clone https://github.com/jlfwong/speedscope.git + cd speedscope + npm install + npm run serve + +This should open up a running version of speedscope in your default browser. + +In your terminal, you should see something like this: + + $ npm run serve + > speedscope@0.7.1 serve /Users/jlfwong/code/speedscope + > parcel assets/index.html --open --no-autoinstall + + Server running at http://localhost:1234 + ✨ Built in 7.30s. + +Most of speedscope is written in TypeScript. If you're unfamiliar with +TypeScript, then you can either just try to learn it as you go, then the +[official TypeScript +documentation](https://www.typescriptlang.org/docs/home.html) may be of use +to you! + +If you're not sure where the code you want to modify lives, the [`README.md` +in the `src/` directory](./src/README.md) might be helpful. + +## Code formatting + +All TypeScript code in speedscope is automatically formatted with +[Prettier](https://prettier.io/). This means that while you're writing your code, +you don't have to worry about following a formatting guide, because a program will +format your code for you! + +The easiest way to use Prettier is via an editor integration. See the [Editor +Integration](https://prettier.io/docs/en/editors.html) page from Prettier's +documentation for help with that. + +If you don't want to do that, you can alternatively run the autoformatter by +running `npm run prettier`. + +## Running tests + +All TypeScript tests are written use [Jest](https://jestjs.io/). To run the +tests, run `npm run jest`. + +## Contributing new features + +Before contributing code to implement a new feature, please open an issue to +discuss it first. Large pull requests that are submitted without first getting +maintainer buy-in are unlikely to be reviewed or merged. + +For features that will cause a visual change, please include visual mockups of +the change you're planning on making. + +## Contributing bug fixes + +If you discover a bug, please file an issue. If the code change required to +fix it is small (< ~20 lines), then feel free to just open a PR to fix the +issue without trying to get buy-in ahead of time. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..29d4ec0 --- /dev/null +++ b/src/README.md @@ -0,0 +1,13 @@ +# Speedscope TypeScript source + +This directory contains the bulk of speedscope's source code. + +## Subdirectories + +* `gl/`: WebGL code. This includes e.g. the code to render flamecharts. +* `import/`: Code to import profiles from varous profilers into speedscope. This include e.g. the code to import Chrome performance profiles. +* `lib/`: Mostly dependency-less utilities. This includes e.g. an LRU cache implementation, basic linear algebra classes, + and the definition of speedscope's file format. +* `store/`: Speedscope's application state management. Implemented using [`redux`](https://redux.js.org/). +* `typings/`: [TypeScript definition files](https://basarat.gitbooks.io/typescript/docs/types/ambient/d.ts.html) +* `views/`: View code to generate the HTML & CSS used to construct the UI. Implemented using [`preact`](https://preactjs.com/) and [`aphrodite`](https://github.com/Khan/aphrodite). Also contains code mapping from the `redux` store to views using [`preact-redux`](https://github.com/developit/preact-redux)