Home / GitHub Page

Let's Discuss Improving Documentation and Styling Guidelines To Help New and Old Contributors

I’m off work today and am briefly looking into it myself. I don’t have much of a clue about how to use it but am willing to learn. I also think that having a #GSoC-Doc Discord channel for everyone that is contributing directly to this project would help everyone stay up to date better. What do you guys think?

I really think this would be an excellent project to get going and submitted for GSoC

it is good for quick talks, but information there are lost, so anything what shall be available in the community has to be in the forum.
We are working on it to improve the flow of information.

I’m not that much further, I only noticed that it is used very often and you can quickly create structures docs.
Give me some idea of the first structure and we will continue from there.
Idea:

  • Architecture
  • Style
  • Def tools
  • Build
    • checks
  • Contribution
    • style
    • show proof of fix

Here’s my thoughts so far:

If you want all contributors to use the same tools and whatnot, you’ll need to settle for Visual Studio Code or something similar. There aren’t really any cross platform IDEs for React and Javascript that are universal to all major platforms, so my recommendation is the next best thing. It also would require Arch and Gentoo users to either downgrade their kernel to 5.4 or change Linux distributions altogether due to multiple bugs that are predominantly on rolling release distributions due to their bleeding edge nature. And these bugs are primarily related to Electron and Chromium.

OBS-Studio is a great option for screen recording for those that want to show their tests in real time and use video / gif as their proof of fix. It works extremely well across all platforms.

Each platform has their own apps for taking screenshots of the desktop and apps that are being run / tested. Scrot is a great command line tool for Linux. Screengrab is one of the better gui based ones that has support for a variety of resolutions and compression types. It’s also a default app in many desktop environments.

Some projects require github contributions to be made by users that use their real names and have some kind of identifying information (like a portfolio or resume attached to their accounts) to allow the devs to verify that they are qualified to work on the project. This is something that would be important to decide on and add to the documentation.

There should be set rules and guidelines for how tests should be performed and those that don’t show valid results (like my video example above), their bug reports and fixes should not be accepted.

Minimum requirements of tool knowledge to be able to contribute and / or test Joplin.

1 Like

I expect that to be in the proposal:

About me

Provide your contact information (IRC nick, email, IM, phone) and write a few sentences about you and why you think you are the best for this job. Prior contributions to Joplin are required; list your commits. Name people (other developers, students, professors) who can act as a reference for you. Mention your field of study if necessary. Now is the time to join the relevant irc/telegram channels, mail lists and blog feeds. We want you to be a part of our community, not just contribute your code.

Tell us if you are submitting proposals to other organizations, and whether or not you would choose Joplin if given the choice.

Is that enough?

I hadn’t checked into that document. Thanks. I was meaning for the general project and not specifically GSoC. And you asked for general places to start and i was just saying what was off the top of my head in that moment. Ha

same idea here, but GSoC is the most urgent currently

1 Like

Most definitely. Could GSoC be kind of a test bed for how the rest of the project will go in the future if things go well with that?

I would say the entire GSoC thing is test bed for us in many regards :grin:

2 Likes

Count me in. I am ready to see what happens. Ha

I’m starting with giving GSoC 2020 live blog structure.
I’ll continue collecting. As soon as I have significant additional amount of bullet points for contribute, built and troublehshooting, I’ll derive readthedocs from it

I disagree with telling people to Google before needing help with an issue only because not everyone knows where to properly look for help or what exactly the kind of help they’ll need is. Many times, Google searches will take people to stack overflow and other forum posts that may not necessarily offer what they’re looking for or offer the wrong information. Here’s my suggestions on two good resources for possibly common questions.

Reactjs: https://reactjs.org/
Electron issue tracker (if working on Desktop client and running into unusual behavior): https://github.com/electron/electron/issues

agree with you, it has to be rephrased.
The background is that there is a lot of activity in #gsoc. If all of them ask question what can be solved by google it up within a minute, it is a real pain explain it to all.
At certain point we have to protect ourselves, avoiding that we are overrun by question and missing the one who really need support.
It is thin line between blockage and asking for independent troubleshooting.

How shall we solve this dilemma?

2 Likes

I see your point there. I’m not completely sure what the best option would be here. The core problem with them Googling answers to their questions is that the solutions they come up with may not be remotely what you are looking for, leading to a nightmare on your end too.

Is there any way to increase the amount of help you have so that you can focus on what really needs it? Maybe have a system of checks where lower level users review the students’ proposals before they get to you?

that would help fore sure, we could says

  • google 5 min
  • ask the community
  • mention specific user

Moreover, we could agree on loose multi-level support

  1. community
  2. very active user
  3. GSoC programm mentors etc.

that could mitigate the message

2 Likes

Anyway to enact concrete roles outside of mods and users? I like this and it’s already sort of in place.

mods are

not that much

that is anyone but not all of them are as deeply involved as you

I think , it would be highly helpful if there is documentation on the codebase and its organization.
I admit I am new to react, There are a lot modules used in Joplin which makes reading through the source code difficult and hard to navigate.
An example about project layout would be neovim-project-layout
Some files are too long (1000 lines) they have multiple classes, may be this something that could be improved through refactoring the code.

1 Like

I disagree, since it’s opensource the codebase it constantly evolving and it would be really really hard to maintain a documentation for the codebase, secondly, I’m with you, it might seem a bit daunting at first but you just need to get your hand dirty and dwell in the code base, piece by piece it will start making sense, one recommendation I can give you for easy navigation is use the search file feature in VSCODE, by typing few keyword you can easily find out which file is affecting the part of the codebase you want to edit.

2 Likes

Thank you, your recommendation is really helpful. I do use search feature (grep) to locate relevant part of source code and code folding to understand the large files but this is not good for understanding the overall structure of the project.
Consider this example from neovim.
If I want to make a certain change,I know where I should look into the source code.


If the code has been documented about high level components this would be more helpful for new contributors.

Perhaps some high level doc about the app architecture would help? Do you have any example of an open source project that provide a good arch doc that we could take inspiration from?

There are always things to improve but overall I think the code is relatively well organised, with models, services, views, etc to split functionality.

2 Likes