spec
benawad opened this issue · 35 comments
Marketplace for Code Reviews
- Home page
- List of code reviews
- display name, programming tags, and link to GitHub url
- List of code reviews
- GitHub OAuth for login
- Create code review
- name (max length 30 or something)
- description
- github repo (selected from dropdown)
- programming language tags (max of 3)
- list of questions (max of 10 questions)
- View code review
- reviewer answers questions
- send email to the other person when code review done
- see who reviewed and what they said
- public, anyone can see this
- rate the person who reviewer
- reviewer answers questions
- My code reviews page
- list of code reviews given and the rating received
- list of code reviews received
- NavBar
- display average rating
- Code Review Briefing
- number of questions/flags
- list of questions
- code snippet
- comment thread
- click to go to file where code snippet came from
The first question I get asked when requesting a code review is 'What are you trying to do?'. You should add a description field when creating code review, it will be easier for reviewers to quickly decide if they want to review it rather than visiting the github and scanning the (potentially useless) README.
Maybe adding a category to classify the different type of goals for the code review.
for ex: bug, quality control, structure prototyping, mentoring (use live share of vs code or another tool?), ...
Bugs category gives the possibility of transforming code ponder in a help forum... That shouldn't be the main focus of the app (i think), but it will grab a share of a gigantic market.
On the other hand, the categorization should be more broad than the examples given above.
A classification too detailed will only add complexity without sufficient benefits.
A good addition would be a more opinionated form when creating the code review request and its description. It should follow some template that would help the user give better info about its goal. There could even be different templates for each category of request.
That would help avoid common descriptions like "Help! Everything is wrong!" ;)
The same can be done for the final rating by the requester. A rating more semantically rich would give much more info to future requester.
As for the regex used in the github url, i think it is not necessary. Github has a graphql API that could be used to check the validity of the url.
For the code review, an advanced feature could be a chat channel associated for each one or one could use just the format of a forum, where the code review page would be like a thread with posts.
@Remulos great idea, I'll add that as a field in the form
- I like the idea of categories and having templates for them. I think at first I'll have a generic form, see how people use it, and then add categories/templates.
- I agree about the ratings, any ideas on ways to do that?
- I'll use the GitHub API to fetch all the users repos and have the user select from a dropdown list
- Chat is something I want to do, but I will save it for later iterations
2. I agree about the ratings, any ideas on ways to do that?
I think a better rating workflow should be based on what browsing requester are interested to know. Here are some potential ideas to seed the structure of the rating, but they should be better reviewed in the future (also there shouldn't be to much of them, just enough to give a good idea):
- Interpersonal: good at explaining or teaching, good english language, approachable character, trustiness (too generic), ...
- technical: knowledge in specific areas, ease of problem solving, ... (maybe base this on the future categories of the request?)
- time management: quick to help and answer, ...
Of course not forgetting a comment field.
One other possibility could be that the overall rating would be automatically calculated with the 'sub-rating' given by the requester...
The spoken language could be also a feature. That would give the possibility to join people with native language other than english. This does not mean a multi-language app. The app's official language could still be only english.
From all of this, an interesting feature arise. The users would have Projects/Repos as atomic objects and each projects could have different requests. This is a natural occurrence, if for example, i had a request today for the same project where other requests have already been solved. This is only in the point of view of the requester. The implementation shouldn't be to different from just using requests.
That would had a component/page to manage the project/repos in the application to your specs.
- I'll use the GitHub API to fetch all the users repos and have the user select from a dropdown list
Just wanted to mention this, maybe allow gists too.
One requester could put its request as simply public, but he could also add specific code reviewers by name. Those reviewers would then get a notification of a request to review.
This brings the necessity to facilitate the access to the reviews of an user. Which bring a Profile page for each of them, where, beside the reviews given to them, they could put a brief bio, foto, avatar, companhy logo and url, other usual contact info...
One other feature would be to give the possibility to code reviewers to also rate their interaction with the requester. This would help future users to decide if they want to accept the request or avoid waste of time, inter-personal head-heck or simple trolling.
Which invokes a system to help users tag requests as spam or trolling...
One other thing that the spec are missing is an admin section of the app and a help-desk/issue system.
This brings the necessity to facilitate the access to the reviews of an user. Which bring a Profile page for each of them, where, beside the reviews given to them, they could put a brief bio, foto, avatar, companhy logo and url, other usual contact info...
One other feature would be to give the possibility to code reviewers to also rate their interaction with the requester. This would help future users to decide if they want to accept the request or avoid waste of time, inter-personal head-heck or simple trolling.
Which invokes a system to help users tag requests as spam or trolling...
This is increasingly sounding like a niche clone of fiverr or Upwork.
To be clear, I'm not saying that's a bad thing, they're both massively popular sites and certainly inspiration can be taken from them. If reviewers are going to have some sort of profile page, I would suggest something like this JS diff checker as a good tool to show off some types of work. Code cleanup for example.
This is increasingly sounding like a niche clone of fiverr or Upwork.
I am only adding thing, taking in mind a full fledged app, but i do not know the vision that @benawad has for this app. He will be the final deciding factor in everything.
Nonetheless most of the features that he decide to add will certainly be divided in different phases of the app. The main goal should be to have a 1º usable version with minimum usability.
This brings the necessity to facilitate the access to the reviews of an user. Which bring a Profile page for each of them, where, beside the reviews given to them, they could put a brief bio, foto, avatar, companhy logo and url, other usual contact info...
They are singing in with GitHub which contains most of those + open source contributions and personal projects.
They are singing in with GitHub which contains most of those + open source contributions and personal projects.
That is an excellent point. Github has a wealth of info that could be used and reorganized automatically to give a better profile and doesn't have to be in the app database.
Consider taking a look at Gitpod. It's not like Codeponder in essence, but they both integrate with GitHub in a pretty integral way. Gitpod is basically a VS Code like experience for any GitHub repo, and the way you open it up is: https://gitpod.io#<full-github-url>, e.g. https://gitpod.io#https://github.com/benawad/codeponder/.
I can definitely see something similar going on to get started with Codeponder - https://codeponder.com#https://github.com/benawad/codeponder/pullrequests/1 to either submit one (if you're the repo owner), or review it (if you got to it via GitHub).
They also have a Chrome extension, which adds a button inside GH to open it in Gitpod, so something similar would work quite nicely here too, where you have a button that could also have some basic information on it, relevant to Codeponder:
WDYT?
How can we avoid being too similar to upwork?
One would have to change the business model.
upwork's is more in line with an online service that principally sells tools to solve problems in exchange for money.
There are much more alternatives out there. One that has been very successful is the gamification strategy used by for example by stackoverflow and co.
- The main service is free and public which let the users contributing have something to show/brag to others/employers. So their stackoverflow profile is the same as a portfolio
- Many users also simply like to help others. And answering is one of the best ways to learn.
(i personally love and respect stackoverflow. I think that they have done a great work. Do not let my earlier word like 'brag' give an erroneous impression). - The whole interactions are awarded points, badges, etc which serves to ranks and promote the users.
- ...
As for monetization, this is good read: What is Stack Overflow's business model?
tltr (taken from the aproved answer):
- Job listings (e.g. the traditional classified ad model)
http://careers.stackoverflow.com/employer/about-listings - CV Search (e.g. the new-fangled and IMO vastly superior dating model)
http://careers.stackoverflow.com/employer/about-search - Traditional, but respectful (e.g. no animation or flash or pop-anything) display advertising on SO, SF, and to a lesser extent SU. http://stackexchange.com/about/contact
- Stack Overflow for Teams
I think I like that business model better
This might not be the best place to put this comment, but it involves several random ideas and i do not see the necessity to open new issues. And it does have some relevance to decide the specs...
I have seen your new video and i do like your idea. You probably will have much more work to do, but i have no doubt that it will be rewarding.
Here are some things that may help:
- VS Code has a web version of its editor that could be used in its entirety as a package or as inspiration: Monaco Editor and one can see a demo here. Many other alternatives exist ...
- to get the code from github one can use the Graphql API. Some example (to quickly demo without a server use the Github GraphiQl, you may be asked to give some permissions to the Github web app the first time...):
- get the code from a file (the code come in simple text format)
{
repository(name: "codeponder", owner: "benawad") {
object(expression: "master:packages/server/src/index.ts") {
... on Blob {
text
oid
}
}
}
}- get the files and their code in a given repo (this example goes 1 step deeper in the tree)
{
repository(name: "codeponder", owner: "benawad") {
object(expression: "master:") {
... on Tree {
entries {
name
type
object {
... on Blob {
text
}
... on Tree {
entries {
name
type
object {
... on Blob {
text
}
}
}
}
}
}
}
}
}
}- to get the info on gist (unfortunately i do not see how to get the code...)
{
user(login: "benawad") {
avatarUrl
bio
company
email
gists(first: 5, orderBy: {field: CREATED_AT, direction: ASC}) {
edges {
node {
... on Gist {
id
}
id
description
name
}
}
totalCount
}
}
}One thing to note is that a user do not have to get any special permission to access common data from other users
@audiBookning I see using the graphql api to get metadata on the repo, but is that the best way to get the code? We want all the files, so we would need a way to request all the levels. I'm thinking maybe we get it by downloading the zip, but I'm not sure if there's a better way.
We want all the files, so we would need a way to request all the levels
I was under the impression that the app would only request the files that it need for the review and save only references to them. The server would only manage the comments and the files would maybe only be fetched by the user's browser. This would avoid the storage and management all of them and adding a much greater weight to the server. Also the fact that the users browser is the one that makes the request to github, would also avoid some possible problems with rate limiting from github (not sure about this).
To achieve the storage of all the files, the graphql API doesn't seem the better option. It seems to me that the best would be to either have git installed on the server or just use a package like NodeGit
Another alternative would be to not reinvent the wheel and use an editor that already has all of those features. I mentioned monaco editor, but it has only basic features. Fortunately CodeSandbox is a much more advanced editor based on monaco that is very similar in its features to Gitpod mentioned earlier also and seem to have many others. Better yet, it has a github repo and is GNU General Public License. Some small adaptation and filtering would probably necessary. Or one could simply use it as a source of inspiration.
There are others package with interest:
- Ace (Ajax.org Cloud9 Editor)
- Tedit is a git based development environment. When I say git based I mean you don't edit files on disk. You edit git databases directly. Visually it looks much like a traditional editor complete with file tree and editor pane. Under the hood, you are browsing the git database graph and creating new nodes and updating the root reference whenever you make a change.
- Wcode is a rich code editor which runs inside a browser. It's totally inspired on Visual Studio Code, and also uses Monaco-editor as it's core engine for providing a rich experience. It is being developed with Node.js + Express + React.
- A simple boilerplate for Monaco editor with React.
- Monaco Editor for React
Also the fact that the users browser is the one that makes the request to github, would also avoid some possible problems with rate limiting from github (not sure about this).
This is taken from the GitHub API Documentation:
For API requests using Basic Authentication or OAuth, you can make up to 5000 requests per hour. Authenticated requests are associated with the authenticated user, regardless of whether Basic Authentication or an OAuth token was used. This means that all OAuth applications authorized by a user share the same quota of 5000 requests per hour when they authenticate with different tokens owned by the same user.
For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests.
The Search API has a custom rate limit. For requests using Basic Authentication, OAuth, or client ID and secret, you can make up to 30 requests per minute. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute.
Also, Wcode looks good, I might have to try using it myself!
Rate limiting :(
Also, Wcode looks good, I might have to try using it myself!
You should look at CodeSandbox, it has all of wcode features and much more. The problem is that for simples things it may have too much and be too complicated.
I'm thinking of taking a snapshot of the code from GitHub and storing it on something like s3. Then I don't have to worry about the rate limit and the code will never change this way.
I'm thinking of taking a snapshot of the code from GitHub and storing it on something like s3. Then I don't have to worry about the rate limit and the code will never change this way
Unless you want to convince people to use your git service, you may have to maintain the code in sync with the origin. Github has Webhooks that would help in that.
If you use them, it might a bit unrealistic to sync every time a webhook is triggered. Imagine the case of one person heavily and constantly pushing to origin. This behavior multiplied by many users would be bad for the app (big traffic in an app is also great news!).
As a solution, one could 'store the triggers' and only act on them when someone visits the page of the app where the code review is visualized.
One added performance feature, would be to 'put the triggers' in the queue of a regular batch cron job? I am not too sure about the benefit of this one, but it is a normal strategy in dealing with caches and, in practice, that will be what your code snapshot would be.
@audiBookning the questions are only relevant to the original versions of code so I don't see why would you constantly sync it? If someone completely changes a file the question would lose all it's meaning plus it would be hard to keep "flagged" lines of code in sync with the actual code.
@sterjoski I may not be visualizing correctly the app, but consider this argument. You are right if the question posed by the review is a simple one. But solving a minimally complex problem is normally a process with different iterations. worse if there is some misunderstanding in the communication. The app should be able to stay relevant with the latest changes in the code.
it would be hard to keep "flagged" lines of code in sync with the actual code.
Yes that will be one of the greater obstacles that the app will have to surmount (even without the added sync). A feature to diff the versions of the files seem to be a must to deal with this... That might be also the way to 'flag' the lines of codes and maintain a good enough reference to 'position' the comments?
I see it as something that doesn't know about the git history and if you want to rework the code and get a second review then you can make another post.
If you want to do many iterations pick GitHub or another tools.
If you want to do many iterations pick GitHub or another tools.
That is fair :)
So the preferred workflow would be to take a snapshot of the files when the review request is created, store those files (essentially the up-to-date repo minus the git history) on your server, have reviewers edit or comment code in an browser editor (like code CodeSandbox or Wcode) and then push those changes to the repo once the review is complete, once the review is completed, each party can rate the other to some degree or another on a variety of topics (professionalism, quality of comments, standard of code, etc.).
have reviewers edit or comment code in an browser editor (like code CodeSandbox or Wcode) and then push those changes to the repo once the review is complete
I'm thinking the reviewers can write comments, but not edit the code.
I'm thinking the reviewers can write comments, but not edit the code.
Since there is a comment section the author and the reviewers can go back and forth on implementing a specific code snippet or whatever.
Make the comments support Markdown and add Prism and you are all set.
Make the comments support Markdown and add Prism and you are all set.
If there is no code editing, that would be much simpler to implement.
I'm thinking of taking a snapshot of the code from GitHub and storing it on something like s3. Then I don't have to worry about the rate limit and the code will never change this way.
this is the better way of doing this, but the disadvantage is it need separate architecture for managing massive code base data in your s3, bucket , add some corn jobs for cleaning after review is closed.
guys please check this opensource project for live interactive code IDE on browser easy for expert debug there code in browser at any place. and they just need to hook the github repo link with IDE
https://github.com/stackblitz/core
To avoid storing things at first, I'm thinking of forking the repo to "snapshot" it and then make all the requests through github's api and then if this get's popular enough that we run into rate limit problems, then move it to s3.
I have found some good sources for inspiration. Maybe some of them can be useful with different strategies to deal with the github repos:
- GitStar - React Apollo Github Client. It is also a mono repo using lerna. It has at least two blog posts that goes along with the repo. Implementing Github OAuth flow in React and Building a Github Client with React Apollo
- GitPoint- GitHub in your pocket. A react native GUI for Github. Here is a blog post about it from its developer, Using React Native to Build GitPoint
- GitHub Desktop. The 'official' Desktop GUI. '... GitHub Desktop is an open source Electron-based GitHub app. It is written in TypeScript and uses React...'
I hope it helps.
Definitely some good ideas here, i wanted to make my contribution and highlight the ideas which i like.
Single page for each repo, various request pages per repo:
I like the idea of having a single page for a repo/project and different request per repo, just as @audiBookning suggested, you can have many different request from one single project and through the life time of the project. (During the very beginning of the life of a project requests could be about back end stuff, graphql schema design, auth issues and going different request like 'react patterns' at later stages of each projects).
Company/startups profiles:
This came up on Discord and i think it's important to highlight right now as @benawad is in the process of designing the database entities. I think company profiles should be added besides single users and reviewers.
I also wanted to accentuate the references to adding webhooks and a live code editor to the application; while definitely good, they may place a sizable weight on the first version of the app.
To avoid storing things at first, I'm thinking of forking the repo to "snapshot"...
One idea is to store certain files to be reviewed where the main logic is and then link to the github repo for dependencies/utilities.
For the feature of repos adding to be reviewed i'd really like to emulate the Netlify experience, if anyone has tried it, it is really straight-forward, you connect through OAuth, select the repo, and deploy (request a review).
Finally i wanted to have the possibility to have more than just 3 tags for the main programming languages, i'd like people to be able to sort not only by programming languages but by libraries as well so also people knowledgeable of those libraries or even maintainers/contributors could review code; so instead of 'React, Typescript, GraphQL' we could have 'Typegrahqpl, Typeorm, etc...".
I also wanted to accentuate the references to adding webhooks and a live code editor to the application; while definitely good, they may place a sizable weight on the first version of the app.
Yes. Although i shared many of the code editor links, i am becoming more and more certain (just sharing my opinion) that it isn't, at this time (and even maybe for much more advanced versions of the app), a good path to pursue, not only for the type of application that Ben seem to envision but also for many similar to it.
And that is for many reasons, including weight and complexity not only for the code, but also for the UX part. It will probably confuse too much the workflow of the reviewing process without adding real value to balance the steeper access and learning slope to the functionalities of the app.
One could argue that, in an advanced version of the project (who knows what the future entails...), if the app had a feature to transform the edited code in pull request, that it may have more value. But, as Ben mentioned before, it would only be needlessly recreating Github.
One must not forget that most developers already have setup a trusted workflow and tools to code and share that code. The main goal of a reviewing application shouldn't be to replace them. Worse is, as it would smear the core of the business model like one in the lines of stackoverflow (as mentioned on a previous post) and many others business models.
Although the markdown approach or a similar simple one for quick and dirty code reviews should be considered.