Breaking up issues into GitHub projects

[sirinoks]

To have an idea of where the project is going we need to maintain a structure to our issues. GitHub projects offers such structure.
It was used before in Telescope, and was later abandoned. Currently we need people that will look at issues, figure out what they are about and assign them to a larger chunk of development in projects, or creating a separate project. For now we have assigned @sirinoks and @JerryHue to do that.

Using projects will help:

• New people to see where to apply themselves;
• Maintainers to see where the project is going and which areas are lacking;
• Any past maintainers to see the progress of the project, making it easier to go back in and get involved again.

You can now help out and see how we work on this is this discussion. The issue will get closed once we have identified all projects and assigned all issues to a project.

Once this issue is closed, a new one should be made. It would describe the latest state of Telescope and will require a new person to be responsible for its maintenance once this semester is over.

[cindyorangis]

Hi @sirinoks,

I love your fresh ideas on tackling multiple problems that Telescope has right now. I'm an alumni of Telescope and I also find it difficult to keep track of the ongoing changes happening with Telescope. You really have to dig around to find things. It's great to see that you're seeing all these challenges we are facing and the main ones I was able to pull from this are:

1. Project Management
   One of the tools we used for Telescope 0.5-1.0 is GitHub's Project board. I looked around to see if we continued to use the project board since 1.0 and unfortunately, it hasn't been used. I personally enjoyed using the board as it gave us a visual overview of:

• What needs to be done
• What's in progress
• What needs review
• What has been completed

Every item on the board was either an issue or a pull request. We also used tags to prioritize the issue: High, Medium, Low, Nice to have

Example board https://github.com/Seneca-CDOT/telescope/projects/10

On a side note, while you may be asked to pick an area of interest when you first start working on Telescope, you'll likely be working on many different areas of Telescope. For example, in one release, you may be working on the frontend, then in the next release, you may be working on something backend-related.

2. Architecture Diagrams
   I couldn't find the complete list of tools and technologies we're currently using. We could use some diagrams to show how the tools and technologies work together.

3. Documentation
   Do you know what's worse than spaghetti code? Spaghetti docs and it doesn't have to be that way! Someone, please organize the docs... I'll frame a picture of you in my living room and appreciate your efforts for years to come Convert our GitHub docs to MDX in Next.js #290

[AmasiaNalbandian]

Hey Alex! This is not a bad idea!

I would also say to split up front-end and back-end. We have handlebars, and then just React in other parts. For the front end same thing. The project is so big that it uses a bit of everything. I also wanted to add I am still very confused about the containers and how to run which for what. That might also be helpful.

[sirinoks]

Now that I'm changing the direction of the issue, I will leave the previous content of the post in here as a comment, so that we have it somewhere.

[sirinoks]

What would you like to be added:
A visual way to overview our project with all its parts.

Why

As a new participant I quickly became lost in all the areas of Telescope. I knew for sure there is a website which should have front and back end, but as for everything else surrounding it - there wasn't a clear picture. The most useful data I found was in a text form, which gave me some idea, but yet was not clear enough. There should be a better way to just show what we're dealing with... And that is exactly my proposition.

Please note this is only my first draft of the idea, everything here can and will be discussed and potentially changed. I need your input!

Looks

I have a couple of versions of how I see it done. The biggest problem is how to show all we have visually. Here is where I want your suggestions, since my example doesn't look that great IMO. Also please note this is just an example to have at least something to imagine as a final product. Things aren't aligned, colored, placed all that well in here, but hopefully give you the idea of what I'm trying to say.

View 1

Basically, we have the major areas that we can divide anything in. The placement of the project is based on how much of the project is in those said areas. Here is where it becomes complicated - there will need to be a code that will calculate the project's position and size based on the data.

View 2

Another way to show this would be the other way around - each project would consist of major areas that will divide it. This one seems easier to implement, since now positioning doesn't matter as much.

Issues vs PRs

There is this panel where we choose what exactly we want to view, PRs vs Issues I think is a useful choice

Zoomed in view

As we zoom in, however, I have a clear picture of how things should look. We will get a bunch of PRs or Issues,, depending on what is selected.

Each PR data is taken from GitHub. Same with contributors. Click on the PR - get redirected to a concrete PR.
We could have different borders for things like "review needed", "abandoned", "postponed" to indicate the PR's state.

As for issues - same idea, different data.

Labels will have the same color code as the actual labels of issues. When hovered on - will show the name of the label. Click on it - will link you to every issue of that label.

Side panel

What about that side panel?

Oh, many things could be here.

Milestones, help requests, contributors. Filters?

Now, enough with my scuffed photoshop examples. How would it work?

Connecting data

The easiest way to make it work is to have all data come from GitHub. We already have contributors, issues, PRs and labels from there. Even for things like areas we already have a specific label. For projects we could use an issue that would overview the main point of the project. Could be a wiki page, or a discussion (does anyone know if we can get that kind of data from GitHub?). A single place that would just explain what the project is about.

Using data just from GitHub allows us to not ever worry about creating our own tools to create new items in the visualisation. No need for a database. Just parse the data we already have in the repository.

---

Alternatively, we could add a classic "add/edit/delete" functionality, however that is just extra work as opposed to having it all come from GitHub.

How to make

This will be a web application. We will need to connect to GitHub API for its data. As for visualisation - I don't know how specifically we would have that shown. Back in the day I know people used html maps, or flash, or some framework. That part would need to be researched. We will also need to host this somewhere.

The biggest challenge would be to write an algorithm for placing and enlarging/lessening the boxes. Could it just be done with CSS flex and percentages? Let me know if you have an answer.

Why would you like this to be added:

Problems solved

• Where in Telescope for a new person to go
• Visually see the state of the project
• Find abandoned PRs
• Moving people from popular to less popular areas

Tell me

I need your feedback on this. Here are the questions to think about:

1. Do we need this?
2. Is it worth to develop?
3. How to better visualiase areas?
4. How to position everything?
5. Any ideas of your own?

If we ever decide to actually make this, I will need help - in no way I can code this alone. Let me know!

[JerryHue]

@sirinoks, is there something else we have to do for this specific issue? I remember that this issue was technically done, and that you'd like to close it. Is there a reason why you haven't closed it yet?

[sirinoks]

@sirinoks, is there something else we have to do for this specific issue? I remember that this issue was technically done, and that you'd like to close it. Is there a reason why you haven't closed it yet?

The reason is the new project, I will need to ask what it is about and bring some general structure to it. However, it can be decided that that new project is outside of the scope of this issue. If it is - then there are just small things left to be complete.

Specifically, the Supabase project and some details in the Search project. These things can be also filled out by people related to those projects. If you want to assign help, these are the themes people need to be familiar with.

I am planning to finish it soon, it is my current priority. Do you need me to finish it for a specific deadline @JerryHue?

[AmasiaNalbandian]

I'm closing this issue - the main issue for this was to handle the set up of the Projects. This has been completed.

I have filed TWO issues for:

1. Search Project
2. Supabase Project

@sirinoks These need to be done before 3.0 alpha, please start pinging who you need to help complete the documentation.