Difference between revisions of "GSOC newcomers"

From GCompris
Jump to: navigation, search
(quickgit is replaced with https://cgit.kde.org/gcompris.git)
(change branch scheme to be able to force push locally)
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Write a sok/gsoc proposal ==
+
== Write a SoK/GSoC proposal ==
 
You are a student and want to participate to either sok or gsoc. For this, you have to write a proposal on what you plan to do.
 
You are a student and want to participate to either sok or gsoc. For this, you have to write a proposal on what you plan to do.
  
Important note: if you don't follow this, your application will not be considered.
+
Important note: If you don't follow this, your application will not be considered.
 +
Other Important note: Do not start working on the tasks before the selection process is done. Several students may want to propose for the same task and it wouldn't be fair to them to block the task.
  
 
=== Idea pages ===
 
=== Idea pages ===
 
There are several pages that can help you find what we'd like to see on GCompris:
 
There are several pages that can help you find what we'd like to see on GCompris:
* you can navigate in our phabricator pages: https://phabricator.kde.org/project/view/1/
+
* You can navigate in our phabricator pages: https://phabricator.kde.org/project/view/1/
* there are ideas here: http://gcompris.net/wiki/Ideas_for_activities
+
* There are ideas here: https://gcompris.net/wiki/Ideas_for_activities
 
* https://bugs.kde.org/buglist.cgi?quicksearch=gcompris&list_id=1393147
 
* https://bugs.kde.org/buglist.cgi?quicksearch=gcompris&list_id=1393147
 
If you have ideas that are not listed there, don't hesitate to propose them.
 
If you have ideas that are not listed there, don't hesitate to propose them.
  
 
The aim is not to do everything. You have to keep in mind the time length of the event.
 
The aim is not to do everything. You have to keep in mind the time length of the event.
 +
=== Proposal writing steps===
 +
You need to describe what you plan to do. For each activity:
 +
* Write the general purpose.
 +
* Describe of this purpose will be achieved.
 +
* Provide a mockup of each screen you want to realise or improve, describing what the role of the elements are.
 +
* Provide a timeline to know how much time a task will take.
  
You need to describe what you plan to do (which activities, how, if possible have mock-ups...) and give a timeline for the project.
+
The final realisation could be different from what is planned at the beginning but this step is important for you and for us.'''
  
 +
=== Be realistic ===
 +
Review process and corrections take time. In reality as much as the first code completion. Take this fact into account when doing your timeline. We prefer realistic plans!
 +
If you plan to work on several activities, due to review time, at one point of the project you will have to work on them in parallel.
 +
 +
=== Submit ===
 
Send a mail to '''gcompris-devel@kde.org''' with a link to your proposal (github page, google doc, personal website...) and estimated timeline.
 
Send a mail to '''gcompris-devel@kde.org''' with a link to your proposal (github page, google doc, personal website...) and estimated timeline.
 
In the timeline, don't forget that mentors have to review the changes and then changes will probably have to be done in the code.
 
In the timeline, don't forget that mentors have to review the changes and then changes will probably have to be done in the code.
  
 
=== Introduction to GCompris community ===
 
=== Introduction to GCompris community ===
If you haven't gotten in touch previously, we ask new comers to do a little exercise: http://gcompris.net/wiki/An_exercise_for_new_contributors.
+
If you haven't gotten in touch previously, we ask new comers to do a little exercise: https://gcompris.net/wiki/An_exercise_for_new_contributors.
  
 
=== Proposal submission ===
 
=== Proposal submission ===
 
The submission of the proposal must be done on the corresponding website before the deadline.
 
The submission of the proposal must be done on the corresponding website before the deadline.
 +
 +
=== Check table ===
 +
In order to avoid missing steps, refer to this table before submitting your proposal.
 +
{| class="wikitable"
 +
|-
 +
! Steps to do
 +
! Done
 +
|-
 +
| Write project general purpose,
 +
|-
 +
| Draw mockup for each screen,
 +
|-
 +
| Describe the different objects of a view and their interactions,
 +
|-
 +
| Provide a realistic timetable for each project sub part,
 +
|-
 +
| Write down basic tests for each project sub part,
 +
|}
 +
 +
== Selection process ==
 +
 +
The selection process is difficult for both mentors and students. All the students can't be accepted due to number limitations (number of mentors, slots granted by Google...).
 +
 +
On mentors side, we select students depending on several criterias like code quality, autonomy, implication in the project (see following criteria).
 +
If you are not selected, try to not take it as personal failure: for sure, depending on your involvment, it can be hard to accept. But mentors have to make a choice, a difficult one, to select people with their given information.
 +
 +
Do not only consider a GSoC application as your only potential "internship" (it's not an intership: https://developers.google.com/open-source/gsoc/faq) as you are not sure of being selected.
 +
 +
{| class="wikitable"
 +
|-
 +
! Selection criteria
 +
|-
 +
| Mandatory beginner exercise done
 +
|-
 +
| Proposal submitted in time
 +
|-
 +
| Proposal interest
 +
|-
 +
| Did the student communicate with the KDE community before submitting the application?
 +
|-
 +
| Autonomy
 +
|-
 +
| Code quality
 +
|}
  
 
== When accepted ==
 
== When accepted ==
  
Congratulations, you have been selected to participate to GCompris GSOC or SoK.
+
Congratulations, you have been selected to participate to GCompris GSoC or SoK.
 
Here are a few links to start your community bonding period and set up your environment.
 
Here are a few links to start your community bonding period and set up your environment.
  
Line 40: Line 96:
 
It provides a lot of useful tools:
 
It provides a lot of useful tools:
 
* https://phabricator.kde.org/paste/ to paste text (crash reports, code snippets...)
 
* https://phabricator.kde.org/paste/ to paste text (crash reports, code snippets...)
* https://phabricator.kde.org/differential/ for code review
+
* https://phabricator.kde.org/differential/ for code review.
* https://phabricator.kde.org/conpherence/ for having multiple people conversations
+
* https://phabricator.kde.org/conpherence/ for having multiple people conversations.
* https://phabricator.kde.org/maniphest/ to create tasks and follow their achievements
+
* https://phabricator.kde.org/maniphest/ to create tasks and follow their achievements.
  
 
First step is to assign to yourself all the tasks you plan to do in https://phabricator.kde.org/project/view/1/.
 
First step is to assign to yourself all the tasks you plan to do in https://phabricator.kde.org/project/view/1/.
 
=== Using git on KDE ===
 
You can see the git at https://phabricator.kde.org/diffusion/GCOMPRIS/ (or https://cgit.kde.org/gcompris.git if you are not connected).
 
As you will push work on it, you need to clone git@git.kde.org:gcompris.git.
 
 
You can create a branch for your gsoc: git checkout -b mybranch and work on it.
 
Don't forget to rebase on master from time to time.
 
Once you think you finished your activity, you need to create a code review for mentors to comment the code.
 
  
 
=== Informing on your progress ===
 
=== Informing on your progress ===
Line 58: Line 106:
 
Do not hesitate to discuss as long as you have issues to be sure you've understood and fixed all of them.
 
Do not hesitate to discuss as long as you have issues to be sure you've understood and fixed all of them.
  
Also, you need to create a blog detailing what you have done and add your blog posts to https://planetkde.org/ in order to the KDE community to follow what you've done. If you do not have one, you can create one using https://pages.github.com/ or Wordpress. please try to do a blog post at least '''every month'''.
+
Also, you need to create a blog detailing what you have done and add your blog posts to https://planet.kde.org/ in order to the KDE community to follow what you've done. If you do not have one, you can create one using https://pages.github.com/ or Wordpress. please try to do a blog post at least '''every month'''.
  
 
Moreover, using maniphest phabricator, you can describe precisely what you will do, state your task status and this will permit us and you to see where you are in your timeline (late or in advance).
 
Moreover, using maniphest phabricator, you can describe precisely what you will do, state your task status and this will permit us and you to see where you are in your timeline (late or in advance).
Line 69: Line 117:
  
 
* Copyright headers in each source file must contain your copyright if you create them
 
* Copyright headers in each source file must contain your copyright if you create them
* Once your code is done, make some clean up, there should not be any unused variable or file.
+
* Once your code is done, make some clean up, there should neither be any unused variable or file nor commented parts of code nor useless logs.
 
* Follow coding rules and indent properly your code.
 
* Follow coding rules and indent properly your code.
 
* Avoid files with many global variables or functions with too many parameters. This indicates that there is something wrong in your code.
 
* Avoid files with many global variables or functions with too many parameters. This indicates that there is something wrong in your code.
Line 75: Line 123:
 
* Try to follow an object orientated approach by putting javascript functions specific to a QML object within the object itself instead of the global javascript file. This makes it easy to see what's possible to do with a Qml object.
 
* Try to follow an object orientated approach by putting javascript functions specific to a QML object within the object itself instead of the global javascript file. This makes it easy to see what's possible to do with a Qml object.
 
* The preferred graphic format is SVG.
 
* The preferred graphic format is SVG.
* If you take content from the Internet, graphics, sounds or anything it must be credited in a README file in the resource directory. It must name the file, the copyright and the link where you took it. the copyright must be compatible with the GPL.
+
* If you take content from the Internet, graphics, sounds or anything it must be credited in a README file in the resource directory. It must name the file, the copyright and the link where you took it. the copyright must be compatible with the GPLv3 licence.
* We rely on a lot on graphics but not everyone is skilled enough to make them. The good practise is to re-use existing graphics from GCompris (you can easily mix and change SVG files with Inkscape). If no graphic come close to what you need, the first place to check is [http://openclipart.org http://openclipart.org]
+
* We rely on a lot on graphics but not everyone is skilled enough to make them. The good practise is to re-use existing graphics from GCompris (you can easily mix and change SVG files with Inkscape). If no graphic come close to what you need, the first place to check is [https://openclipart.org https://openclipart.org]
 
* If you don't find open content good enough don't worry, the GCompris graphic team will redo them when your activity is ready.
 
* If you don't find open content good enough don't worry, the GCompris graphic team will redo them when your activity is ready.
* GCompris is translated in many languages. Thus, we need to take care of it in the code. All the strings that should be translated must be between qsTr(). Don't put variables in qsTr(), only real strings (in "").
+
* GCompris is translated in many languages. Thus, we need to take care of it in the code. All the strings that should be translated must be between qsTr(). Don't put variables in qsTr(), only real strings (in ""). Also, we need to try to think of all differences of cultures: some languages are right-to-left read/written, ...
 
* Prefix your commit messages by the activity name, i.e: "sudoku, fix bad anchor of the grid".
 
* Prefix your commit messages by the activity name, i.e: "sudoku, fix bad anchor of the grid".
  
 
=== Development workflow ===
 
=== Development workflow ===
 +
 +
You can see the git at https://invent.kde.org/education/gcompris.
 +
As you will push work on it, you need to clone git@git.kde.org:gcompris.git.
  
 
Once you have your KDE account you have commit rights on the GCompris repository and on other KDE projects. But you must not commit on the master branch directly, you must notice the maintainers of GCompris that you are ready and the review process will start.
 
Once you have your KDE account you have commit rights on the GCompris repository and on other KDE projects. But you must not commit on the master branch directly, you must notice the maintainers of GCompris that you are ready and the review process will start.
Line 87: Line 138:
 
Your development must be done in a specific branch on the KDE GCompris git. Name your branch with the following scheme :
 
Your development must be done in a specific branch on the KDE GCompris git. Name your branch with the following scheme :
  
* [sok|gsoc]_[nickname]_[activity_name]
+
* work/[sok|gsoc]_[year]_[nickname]_[activity_name]
 +
 
 +
Don't forget to rebase on master from time to time.
 +
 
 +
You can create a merge request once you have something to show (with title: "''WIP: addition of activity''") and once you think you finished your activity, you can remove the ''WIP:'' tag and ping the mentors for review.
  
 
As we mention, code quality is of major importance. When you get review feedback change your code accordingly and tell you are ready for another review. Understand that it takes time to make review, so please take in account all our remarks and take time to refactor your code to make it clean, simple, logical and easy to read.
 
As we mention, code quality is of major importance. When you get review feedback change your code accordingly and tell you are ready for another review. Understand that it takes time to make review, so please take in account all our remarks and take time to refactor your code to make it clean, simple, logical and easy to read.
 +
 +
=== Check table ===
 +
As mentioned earlier review requires a lot of time. Again a quick check table to help you before submitting a review request.
 +
{| class="wikitable"
 +
|-
 +
! Steps to do
 +
! Done
 +
|-
 +
| Every file must have a license header with your name on it if you wrote it.
 +
|-
 +
| Every strings that should be translated must be between qsTr().
 +
|-
 +
| Variable names and files must "tell' what they do. pointImageRepeater is preferable to repeater.
 +
|-
 +
| Prefix your commit messages by the activity name, i.e: "sudoku, fix bad anchor of the grid".
 +
|-
 +
| Clean unused variables or files.
 +
|-
 +
| Indent properly your code.
 +
|}
 +
 +
== GSoC 2020 ==
 +
Information about GSoC 2020 can be found here:
 +
https://community.kde.org/GSoC/2020/Ideas#GCompris
 +
 +
 +
== GSoC 2021 ==
 +
Information about GSoC 2021 can be found here:
 +
https://community.kde.org/GSoC/2021/Ideas#GCompris

Latest revision as of 20:29, 29 July 2021

Write a SoK/GSoC proposal

You are a student and want to participate to either sok or gsoc. For this, you have to write a proposal on what you plan to do.

Important note: If you don't follow this, your application will not be considered. Other Important note: Do not start working on the tasks before the selection process is done. Several students may want to propose for the same task and it wouldn't be fair to them to block the task.

Idea pages

There are several pages that can help you find what we'd like to see on GCompris:

If you have ideas that are not listed there, don't hesitate to propose them.

The aim is not to do everything. You have to keep in mind the time length of the event.

Proposal writing steps

You need to describe what you plan to do. For each activity:

  • Write the general purpose.
  • Describe of this purpose will be achieved.
  • Provide a mockup of each screen you want to realise or improve, describing what the role of the elements are.
  • Provide a timeline to know how much time a task will take.

The final realisation could be different from what is planned at the beginning but this step is important for you and for us.

Be realistic

Review process and corrections take time. In reality as much as the first code completion. Take this fact into account when doing your timeline. We prefer realistic plans! If you plan to work on several activities, due to review time, at one point of the project you will have to work on them in parallel.

Submit

Send a mail to gcompris-devel@kde.org with a link to your proposal (github page, google doc, personal website...) and estimated timeline. In the timeline, don't forget that mentors have to review the changes and then changes will probably have to be done in the code.

Introduction to GCompris community

If you haven't gotten in touch previously, we ask new comers to do a little exercise: https://gcompris.net/wiki/An_exercise_for_new_contributors.

Proposal submission

The submission of the proposal must be done on the corresponding website before the deadline.

Check table

In order to avoid missing steps, refer to this table before submitting your proposal.

Steps to do Done
Write project general purpose,
Draw mockup for each screen,
Describe the different objects of a view and their interactions,
Provide a realistic timetable for each project sub part,
Write down basic tests for each project sub part,

Selection process

The selection process is difficult for both mentors and students. All the students can't be accepted due to number limitations (number of mentors, slots granted by Google...).

On mentors side, we select students depending on several criterias like code quality, autonomy, implication in the project (see following criteria). If you are not selected, try to not take it as personal failure: for sure, depending on your involvment, it can be hard to accept. But mentors have to make a choice, a difficult one, to select people with their given information.

Do not only consider a GSoC application as your only potential "internship" (it's not an intership: https://developers.google.com/open-source/gsoc/faq) as you are not sure of being selected.

Selection criteria
Mandatory beginner exercise done
Proposal submitted in time
Proposal interest
Did the student communicate with the KDE community before submitting the application?
Autonomy
Code quality

When accepted

Congratulations, you have been selected to participate to GCompris GSoC or SoK. Here are a few links to start your community bonding period and set up your environment.

Introduction to GCompris community

If you haven't done it yet, send a mail to gcompris-devel@kde.org to introduce yourself:

  • Name, country, university... Whatever you want to share that can be useful.
  • Describe what you plan to do in GCompris, which part of GCompris will you improve...

Setting your KDE account

If you don't have one, you need to create a KDE account (https://identity.kde.org/). Then you need to apply for a KDE Developer account (https://community.kde.org/Infrastructure/Get_a_Developer_Account#Apply_for_an_account) and ask for a developer access (precise that you will do GSOC/SoK under GCompris). More information can be found at https://community.kde.org/Sysadmin/GitKdeOrgManual#How_to_get_read-write_developer_access

We also plan to use https://phabricator.kde.org/ to track our progress so you'll also need an account. It provides a lot of useful tools:

First step is to assign to yourself all the tasks you plan to do in https://phabricator.kde.org/project/view/1/.

Informing on your progress

In a work, the most important thing is communication. Without it, we can't know what the other people are doing, if they have issues... Do not hesitate to discuss as long as you have issues to be sure you've understood and fixed all of them.

Also, you need to create a blog detailing what you have done and add your blog posts to https://planet.kde.org/ in order to the KDE community to follow what you've done. If you do not have one, you can create one using https://pages.github.com/ or Wordpress. please try to do a blog post at least every month.

Moreover, using maniphest phabricator, you can describe precisely what you will do, state your task status and this will permit us and you to see where you are in your timeline (late or in advance).

Code quality

We hope that GCompris will be maintained for years if not decades. It is thus important that your code is clean enough to be reviewed and amended by anyone knowing Qt Quick.

Here are some points you have to check:

  • Copyright headers in each source file must contain your copyright if you create them
  • Once your code is done, make some clean up, there should neither be any unused variable or file nor commented parts of code nor useless logs.
  • Follow coding rules and indent properly your code.
  • Avoid files with many global variables or functions with too many parameters. This indicates that there is something wrong in your code.
  • Avoid repeated code. There is an option in Qt Creator to refactor a QML object. It will be put in a dedicated file named after the object id (right click -> refactoring).
  • Try to follow an object orientated approach by putting javascript functions specific to a QML object within the object itself instead of the global javascript file. This makes it easy to see what's possible to do with a Qml object.
  • The preferred graphic format is SVG.
  • If you take content from the Internet, graphics, sounds or anything it must be credited in a README file in the resource directory. It must name the file, the copyright and the link where you took it. the copyright must be compatible with the GPLv3 licence.
  • We rely on a lot on graphics but not everyone is skilled enough to make them. The good practise is to re-use existing graphics from GCompris (you can easily mix and change SVG files with Inkscape). If no graphic come close to what you need, the first place to check is https://openclipart.org
  • If you don't find open content good enough don't worry, the GCompris graphic team will redo them when your activity is ready.
  • GCompris is translated in many languages. Thus, we need to take care of it in the code. All the strings that should be translated must be between qsTr(). Don't put variables in qsTr(), only real strings (in ""). Also, we need to try to think of all differences of cultures: some languages are right-to-left read/written, ...
  • Prefix your commit messages by the activity name, i.e: "sudoku, fix bad anchor of the grid".

Development workflow

You can see the git at https://invent.kde.org/education/gcompris. As you will push work on it, you need to clone git@git.kde.org:gcompris.git.

Once you have your KDE account you have commit rights on the GCompris repository and on other KDE projects. But you must not commit on the master branch directly, you must notice the maintainers of GCompris that you are ready and the review process will start.

Your development must be done in a specific branch on the KDE GCompris git. Name your branch with the following scheme :

  • work/[sok|gsoc]_[year]_[nickname]_[activity_name]

Don't forget to rebase on master from time to time.

You can create a merge request once you have something to show (with title: "WIP: addition of activity") and once you think you finished your activity, you can remove the WIP: tag and ping the mentors for review.

As we mention, code quality is of major importance. When you get review feedback change your code accordingly and tell you are ready for another review. Understand that it takes time to make review, so please take in account all our remarks and take time to refactor your code to make it clean, simple, logical and easy to read.

Check table

As mentioned earlier review requires a lot of time. Again a quick check table to help you before submitting a review request.

Steps to do Done
Every file must have a license header with your name on it if you wrote it.
Every strings that should be translated must be between qsTr().
Variable names and files must "tell' what they do. pointImageRepeater is preferable to repeater.
Prefix your commit messages by the activity name, i.e: "sudoku, fix bad anchor of the grid".
Clean unused variables or files.
Indent properly your code.

GSoC 2020

Information about GSoC 2020 can be found here: https://community.kde.org/GSoC/2020/Ideas#GCompris


GSoC 2021

Information about GSoC 2021 can be found here: https://community.kde.org/GSoC/2021/Ideas#GCompris