Project: Documentation and improve On-boarding to Development #469

Open
by Echolon opened 2 years ago · 5 comments
Echolon commented 2 years ago (Migrated from github.com)
Owner

Hi,

I have a long-term project suggestion. For the development of Pix-Art Messenger the documentation of code as well as the on-boarding to commit and develop on the project should be improved.

I have no special suggestions, but I think an evaluation process can show problems and ideas to enhance. Everyone can be involved. It think this is a project which insures long-term sustainability. So far @kriztan is shipping a lot on his own, which is great (nevertheless shout-outs to the other contributors like @genofire). However, the dependency is very high. If more people would be involved in understanding at least part of the code or the flow of work in here that would have a positive impact to the general standing of the whole project!

What are your thoughts?

  • What can be improved?
  • Did you ever tried to commit but had problems? What were those?
  • What or where would you be interested in to help?
  • What worked well for you?
  • Where to start to commit?
  • Where to start reading the code?
  • How to setup for development?
  • Where to start with the documentation?
  • How can a tutorial look like?
  • How should this be organized?

All of this are simple or basic questions? However, some are easy to present, some are not that clear and must be more specific. Please join the evaluation!

I suggest we focus on documentation and improvement of on-boarding of new people - so share your experience, questions or ideas in that direction.

Cheers,
Ed

Hi, I have a long-term project suggestion. For the development of Pix-Art Messenger the documentation of code as well as the on-boarding to commit and develop on the project should be improved. I have no special suggestions, but I think an evaluation process can show problems and ideas to enhance. Everyone can be involved. It think this is a project which insures long-term sustainability. So far @kriztan is shipping a lot on his own, which is great (nevertheless shout-outs to the other contributors like @genofire). However, the dependency is very high. If more people would be involved in understanding at least part of the code or the flow of work in here that would have a positive impact to the general standing of the whole project! **What are your thoughts?** - What can be improved? - Did you ever tried to commit but had problems? What were those? - What or where would you be interested in to help? - What worked well for you? - Where to start to commit? - Where to start reading the code? - How to setup for development? - Where to start with the documentation? - How can a tutorial look like? - How should this be organized? All of this are simple or basic questions? However, some are easy to present, some are not that clear and must be more specific. Please join the evaluation! I suggest we focus on documentation and improvement of on-boarding of new people - so share your experience, questions or ideas in that direction. Cheers, Ed
Echolon commented 2 years ago (Migrated from github.com)
Poster
Owner

Today in the chat room first suggestion were made:

  • In general attendees liked the idea
  • Documentation on the most imporatant classes, functions, libraries

-- Also suggestion to list some overview documentation @kriztan
-- Improve code documentation itself
-- Where to start in the code? manifest & startui.java

  • Some introductional support for Java programming (Link 1, Link 2, Link 3)

  • What are good way to start with developing within Pix-Art Messenger?
    -- What is the best way to setup an IDE (Integreative development environment)? (android studio, git,...)

  • "Where shall I start with the code???" It's so much I don't know where to start with...

  • How do I create an effective PR?
    -- Write-up/Video from the "idea to the the pull request"

  • https://contribute.funkwhale.audio/

Today in the chat room first suggestion were made: - In general attendees liked the idea - Documentation on the most imporatant classes, functions, libraries -- Also suggestion to list some overview documentation @kriztan -- Improve code documentation itself -- Where to start in the code? manifest & startui.java - Some introductional support for Java programming ([Link 1](https://www.youtube.com/watch?v=r59xYe3Vyks&list=PLS1QulWo1RIbfTjQvTdj8Y6yyq4R7g-Al), [Link 2](https://www.youtube.com/watch?v=oqnLQVFaqYI&list=PLXqaWKDQpdPn4UJ2fOFxl6Yl_DC51FFUL), [Link 3](https://www.youtube.com/watch?v=d7rYddfRm4c)) - What are good way to start with developing within Pix-Art Messenger? -- What is the best way to setup an IDE (Integreative development environment)? (android studio, git,...) - _"Where shall I start with the code???" It's so much I don't know where to start with..._ - How do I create an effective PR? -- Write-up/Video from the "idea to the the pull request" - https://contribute.funkwhale.audio/
TheOneric commented 2 years ago (Migrated from github.com)
Owner

Something this project is already handling very good imho are the issues. The tags already help to categorize them, "Help wanted" is a good indicator and the same goes for assigned priorities. :)
One possible way to build upon this would be a tag for "Good first issue" (or similar) used for low-priority issues that only affected a limited part of the code (or no code at all; eg finishing an uncomplete translation, or adjusting gui stuff). If someone indicates interest in contributing, they can be pointed to these issues and ask for help if they struggle with something on the way.
Best case this provides a stepping stone to learning programming and contributing.

[Documentation]
If enough Java-compliant function and classes are documented it might also be worth to export these as an html page and or an pdf.
Though this alone still doesn't tell one where to start. Besides a chronic lack of time, this is also what prevented me from contributing more than just trivial patches. But depending on the issue one tries to tackle where to start might differ. So instead of one universal "Start here" I think it would be more beneficial to tell how the code is structured (can it be (mostly) broken down into modules/areas that only have little interconnection?) and how is this structure represented in the file structure (in Java: packages). Where are GUI Theme files and definitions, where is the part that does all the lower level network stuff / handles the XMPP protocol / … ?
And additionally: What are the most important function and classes for the overall program flow?
I think having this information available would help a lot.
Refactoring the structure is probably out of the question to not break ties with upstream and make backports more complicated.

[Coding Style]
Something to be considered when a lot of people are working on a project is a common coding style to unify the code and make it more readable. CamelCasing or underscores- or when to use what? Which variables/classes/functions should be written in CAPS or lowercase ? Common prefixes in some cases ? Tabs or spaces – and how many spaces are one tab ? Line breaks before { or only with classes or never ? What is the maximal line length one should aim for, unless special circumstances require longer lines ?
Although there are probably some prior definitions from upstream, as the maintainer @kriztan can just pick whatever he wants, but tell us so we can do the same when commiting ;)
Providing some guidelines on how to document the code might also be a good idea.
Oh and also: what is the target Java version and SDK API ?

[Java/Android Tutorials]
Linking some guides for starting Java and Android Development might be a good idea, but I don't think it is necessary to write up something unique for this.

[PR]
Providing a general procedure, like eg:

  1. Unless it is a simple fix, first open an issue to discuss if the changes/feature you want to make are beneficial and how this should integrate into everything else.
  2. After discussion, start a PR and mention the issue there, so everyone can see this is being worked on. (Name it WIP: ?)
  3. When it's done or you think an important decision must be made or you need a check request a review.
  4. Request Merge. (Also a style preference: should commits be squashed before merge or not — and if not: should every commit to be merged into master be compilable ?)

For bigger projects GitHub also allows you to start a "Project" and define intermediate goals.

How should this be organized

CONTRUBUTING.md , which currently mostly talks about reporting bugs, could be a good place to put a short overview over the different ways to contribute, the guidelines and a link to the full documentation (including the overview of how this project is structured) etc

Something this project is already handling very good imho are the issues. The tags already help to categorize them, "Help wanted" is a good indicator and the same goes for assigned priorities. :) One possible way to build upon this would be a tag for "Good first issue" (or similar) used for low-priority issues that only affected a limited part of the code (or no code at all; eg finishing an uncomplete translation, or adjusting gui stuff). If someone indicates interest in contributing, they can be pointed to these issues and ask for help if they struggle with something on the way. Best case this provides a stepping stone to learning programming and contributing. **[Documentation]** If enough Java-compliant function and classes are documented it might also be worth to export these as an html page and or an pdf. Though this alone still doesn't tell one where to start. Besides a chronic lack of time, this is also what prevented me from contributing more than just trivial patches. But depending on the issue one tries to tackle where to start might differ. So instead of one universal "Start here" I think it would be more beneficial to tell how the code is structured (can it be (mostly) broken down into modules/areas that only have little interconnection?) and how is this structure represented in the file structure (in Java: packages). Where are GUI Theme files and definitions, where is the part that does all the lower level network stuff / handles the XMPP protocol / … ? And additionally: What are the most important function and classes for the overall program flow? I think having this information available would help a lot. Refactoring the structure is probably out of the question to not break ties with upstream and make backports more complicated. **[Coding Style]** Something to be considered when a lot of people are working on a project is a common coding style to unify the code and make it more readable. CamelCasing or underscores- or when to use what? Which variables/classes/functions should be written in CAPS or lowercase ? Common prefixes in some cases ? Tabs or spaces – and how many spaces are one tab ? Line breaks before `{` or only with classes or never ? What is the maximal line length one should aim for, unless special circumstances require longer lines ? Although there are probably some prior definitions from upstream, as the maintainer @kriztan can just pick whatever he wants, but tell us so we can do the same when commiting ;) Providing some guidelines on how to document the code might also be a good idea. Oh and also: what is the target Java version and SDK API ? **[Java/Android Tutorials]** Linking some guides for starting Java and Android Development might be a good idea, but I don't think it is necessary to write up something unique for this. **[PR]** Providing a general procedure, like eg: 1. Unless it is a simple fix, first open an issue to discuss if the changes/feature you want to make are beneficial and how this should integrate into everything else. 2. After discussion, start a PR and mention the issue there, so everyone can see this is being worked on. (Name it WIP: ?) 3. When it's done or you think an important decision must be made or you need a check request a review. 4. Request Merge. (Also a style preference: should commits be squashed before merge or not — and if not: should every commit to be merged into master be compilable ?) For bigger projects GitHub also allows you to start a "Project" and define intermediate goals. > How should this be organized CONTRUBUTING.md , which currently mostly talks about reporting bugs, could be a good place to put a short overview over the different ways to contribute, the guidelines and a link to the full documentation (including the overview of how this project is structured) etc
errhammr commented 2 years ago (Migrated from github.com)
Owner

I'm working on some JavaDoc documentation. I'm new to the code of Pix-Art Messenger but I will try my best to understand what's going on and document what I find out.
Have a look at my work in progress and feel free to give feedback. Once I make some progress I will start creating pull requests to the main repo.

I'm working on some JavaDoc documentation. I'm new to the code of Pix-Art Messenger but I will try my best to understand what's going on and document what I find out. Have a look at [my work in progress](https://github.com/errhammr/Pix-Art-Messenger/pull/1/files) and feel free to give feedback. Once I make some progress I will start creating pull requests to the main repo.
Echolon commented 2 years ago (Migrated from github.com)
Poster
Owner

@errhammr Wow, I didn't expected to get going that quickly! Cool - I think I speak for everyone that this is highly appreciated!

If you have any issues or problem please state them! Those are likely the issues we want to improve on.

Looking forward to you branch commits!

@errhammr Wow, I didn't expected to get going that quickly! Cool - I think I speak for everyone that this is highly appreciated! If you have any issues or problem please state them! Those are likely the issues we want to improve on. Looking forward to you branch commits!
Collaborator

@kriztan

Is it possible to reconnect to my issues?

@kriztan Is it possible to reconnect to my issues?
Sign in to join this conversation.
No Milestone
No Assignees
2 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.