Changes

Summer of Code/2018/attentive migration of wiki activity pages to git (view source)

Revision as of 10:30, 25 March 2018

2,720 bytes added , 10:30, 25 March 2018

Add information about help-activity, bundle-sizes, Miscellaneous section

Line 50: Line 50:

:'''Description:'''

::* At present, the [[Activities#Sugar_Activities]] section in Sugar Labs wiki lists 345 pages.

−

::* These pages individually serves as homepages(containing all relevant information), for different Sugar Activities.

+

::* These pages individually serves as kind of homepages(containing all relevant information), for different Sugar Activities.

::: example: [[Activities/MakeyMakey]] is the homepage for [http://activities.sugarlabs.org/en-US/sugar/addon/4729 MakeyMakey] activity. Whereas, its source-code is hosted at [https://github.com/sugarlabs/makeymakey https://github.com/sugarlabs/makeymakey]

−

::* ~~With every new activity, the volume of wiki.sugarlabs.org is expanding, and thus it is getting harder to maintain all of the stuff at a single place.~~

+

::* as Sugar Labs is moving towards GitHub style of development (see [http://lists.sugarlabs.org/archive/sugar-devel/2018-January/055005.html discussion])

−

~~::* Also,~~ as Sugar Labs is moving towards GitHub style of development (see [http://lists.sugarlabs.org/archive/sugar-devel/2018-January/055005.html discussion])

+

::: for any change to a activity, it gets cumbersome for the developer to update both the GitHub repository and its corresponding wiki-page documentation

−

::: it would be beneficial(and more maintainable) in the long run if these 345 wiki pages were embedded in their corresponding ~~git~~ repositories.

+

::: thus, it would be beneficial(and more maintainable) in the long run if these 345 wiki pages were embedded only in their corresponding GitHub repositories.

:'''Objective:'''

−

::Write a program(or script) to migrate all of the above-mentioned wiki-content to their ~~corresponding git~~ repositories in ~~markdown~~ format, with ~~great~~ attention to quality.

+

::Write a program(or script) to migrate all of the above-mentioned wiki-content to their appropriate GitHub repositories in Markdown(or reStructuredText) format, with detailed attention to quality.

:'''Promised Outcome:'''

−

::100% of mentioned wiki-pages(from wikitext markup) moved to their ~~git~~ repositories(in ~~markdown~~ format).

+

::100% of the mentioned wiki-pages(from wikitext markup) moved to their GitHub repositories(in Markdown/reStructuredText format).

::*Something like [https://github.com/rdrsadhu/portfolio-activity https://github.com/rdrsadhu/portfolio-activity], from [[Activities/Portfolio]]

::**'' this is a fork of the original repository [https://github.com/sugarlabs/portfolio-activity https://github.com/sugarlabs/portfolio-activity]

−

::**'' I'm aware that the README.md file is not optimal.

+

::**'' I'm aware that the converted Markdown syntax of README.md file is not optimal.

−

::***'' I intend to discuss a few things with the community, before starting to optimize the conversion process~~, which will be the most important part of this project~~.''

+

::***'' I intend to discuss a few things with the community, before starting to optimize the conversion process.''

−

::Also, all the current wiki-pages will be deprecated(deleted/moved~~? to be discussed with~~ the community)

+

::Also, all the current wiki-pages will be deprecated(deleted/moved as desired by the community)

Line 79: Line 79:

::For each page to migrate

::* Step 0: Determine to which GitHub repository, it'll be added

−

::* Step 1: from wiki.sugarlabs.org/activities/activity_page, Get source file(wikitext) which is to be converted(to ~~markdown~~)

+

::* Step 1: from wiki.sugarlabs.org/activities/<activity_page>, Get source file(wikitext) which is to be converted(to Markdown/reStructuredText)

::* Step 2: Get associated extra files(images etc) used in the wiki-page

−

::* Step 3: Convert wikitext content to Markdown

+

::* Step 3: Convert wikitext content to Markdown/reStructuredText format

−

::* Step 4: Add ~~Converted Markdown~~ files to GitHub repository mentioned in Step 0

+

::* Step 4: Add converted files to GitHub repository mentioned in Step 0

−

::* Step 5: ~~Delete/Archive~~ wiki-page and associated extra files from wiki.sugarlabs.org

+

::* Step 5: Deprecate wiki-page and associated extra files from wiki.sugarlabs.org

:'''Detailed Technical description of Migration Process'''

:* Step 1: using MediaWiki API, query wiki.sugarlabs.org to get list of all pages to convert

−

:* Step 2: For each page, research and find out(or discuss with mentor/community) where to place them in GitHub

+

:* Step 2: For each page, research and find out(or discuss as needed with mentor/community) where to place them in GitHub

:**''there isn't a one:one correspondence for all the pages and the git repositories''

:**''for example:''

−

:***''in the section [[Activities#Sugar_Activities]], there are at least 20 pages as Activities/Turtle Art/Tutorials/wiki-page-name , which I believe should be in the same ~~git~~ repository

+

:***''in the section [[Activities#Sugar_Activities]], there are at least 20 pages as Activities/Turtle Art/Tutorials/<wiki-page-name> , which I believe should be in the same GitHub repository

:***''Some git repositories already has a README.md file, which contains information not available in the corresponding wiki-page (See [https://github.com/sugarlabs/Measure activity-git-repo] : [https://wiki.sugarlabs.org/go/Activities/Measure activity-wiki-page])

−

:***''The variety is a lot more, which I plan to extensively discuss, before the coding-period starts.

+

:***''Some wikipages contain user documentation which should ideally be moved to the [https://github.com/godiard/help-activity help-activity]'''

−

:* Step 3: For each GitHub repository to push converted ~~markdown~~ files:

+

:***''Some wikipages have already been moved to GitHub and thus repeating the work would result in duplication''

+

:***''The variety is a lot more, which I plan to extensively figure out and discuss as needed, before the coding-period starts.

+

:* Step 3: For each GitHub repository to push converted files:

:** 3.1: Fork the repository (create a copy of the original repository into my-GitHub-account)

:** 3.2: Pull the forked repository (get a local copy of it, in my development machine)

−

:** 3.3: For each file to be pushed into the repository:

+

:** 3.3: Checkout a new branch for changes

−

:*** Using MediaWiki API, query a specific wiki-page, to get its raw source(in wikitext format), and all associated files(images etc)

+

:** 3.4: For each file to be pushed into the repository:

+

:*** Using MediaWiki API, query a specific wiki-page, to get its raw source text(in wikitext format), and all associated files(images etc) used

:*** create a safe backup of the original raw wikitext

−

:*** generate one temporary duplicate file(containing raw wikitext), ~~to convert into markdown format~~

+

:*** generate one temporary duplicate file(containing raw wikitext), for conversion

:*** using pandoc, convert

:*** while the conversion is not perfect (it is difficult or sometimes not-possible, to generate the exact functionalities of a wiki-page into a markdown file. For example, image-galleries)

:**** modify the temporary wikitext file, with attention to every small detail

:**** and convert again

−

:** 3.3: Commit all newly generated files (also the safe wikitext backup; in-case the community decides to keep it for future reference)

+

:** 3.5: Test all changes

−

:** 3.4: git push to Forked Repository

+

:** 3.6: Commit all newly generated files (also the safe wikitext backup; in-case the community decides to keep it for future reference)

−

:** 3.5: Send a Pull Request to original Repository

+

:** 3.7: git push to Forked Repository

−

:** 3.6: After Pull Request gets merged;

+

:** 3.8: Send a Pull Request to original Repository

−

:*** redirect the wiki-page to its git repository

+

:** 3.9: After Pull Request gets merged;

+

:*** redirect the wiki-page to its git repository, or

:*** using MediaWiki API, delete/move contents of original wiki-page

+

::Important:

+

::: Adding documentation to the activity repositories, may sometimes unnecessarily enlarge the activity bundle size;

+

::: in such a scenario, a custom setup.py will be written which excludes the documentation folder.

Line 121: Line 129:

:'''Project Timeline:'''

+

:: I will work 45-50 hours a week, and have decided the goals accordingly.

::{| class="wikitable"

|Week

Line 140: Line 150:

|

* Set up Development environment(Install necessary software, packages, libraries)

−

* Set up a dedicated blog for GSoC 2018

+

* Set up a dedicated blog for GSoC 2018

+

* Dive deep into the codebase of help-activity, and other important areas of the project

+

* Learn how to write a custom setup.py to keep the size of activity bundle in check

* Blog post about my plans for Coding Month 01

|-

Line 268: Line 280: −

:'''Convince us, in 5-15 sentences, that you will be able to successfully complete your project in the timeline you have described~~. This is usually where people describe their past experiences, credentials, prior projects, schoolwork, and that sort of thing, but be creative~~. Link to prior work or other resources as relevant'''

+

:'''Convince us, in 5-15 sentences, that you will be able to successfully complete your project in the timeline you have described. Link to prior work or other resources as relevant'''

:{{highlight | what better way to prove that I can do the work, than doing some 'real' work?}}

Line 284: Line 296:

---------------------------------------

−

:'' Note: I'm aware of the sub-optimal output from pandoc. and that is what I plan to refine during the summer. It will require a lot of careful observations(and maybe some manual cleanup as well according to diverse page content) and thus was not possible to implement in this limited timeframe.''

+

:'' Note: I'm aware of the sub-optimal output from pandoc. and that is what I plan to refine during the summer. It will require a lot of careful observations(and maybe some manual cleanup as well according to the diverse page content) and thus was not possible to implement in this limited timeframe.''

----------------------------------------

Line 304: Line 316:

::** thus hosting a complete repository with all the documentation, will provide greater exposure and surely help to attract more developers and traffic to the community

−

::''Answer 2: ~~SL Community Member-1~~:''

+

::''Answer 2: James Cameron (quozl@laptop.org):''

−

::* ~~Please share your views~~

+

::* As stated in [https://github.com/sugarlabs/activity-abacus/pull/12 this GitHub conversation]

+

::: "Migration is needed because Wiki is not being used now that GitHub is being used. Maintaining the Wiki in addition to GitHub is not sustainable. So we want documentation to move from Wiki to GitHub.

+

::: "So that when an activity is updated in GitHub, the documentation can be updated in the same place at the same time."

::''Answer 3: SL Community Member-2:''

::* Please share your views

Line 332: Line 346:

=== Miscellaneous ===

−

'''~~Is it mandatory~~ to ~~set up~~ Sugar ~~development environment and attach a screenshot ?~~'''

+

'''Send us a link to a pull request or merge request you have made on a Sugar or Sugar activity bug'''

−

: ~~because this project; does neither directly requires, nor depends on~~ the ~~Sugar development environment~~

+

: I went ahead and migrated 4 pages out of the 345 listed. Find the pull request at https://github.com/godiard/help-activity/pull/38

'''Describe a great learning experience you had as a child'''

−

: ~~Coming Soon~~

+

: Learning how to ride a bicycle surely has been one great experience.

+

: Though my father initially helped to ease out the fear; just some weeks later I was alone all by myself, deciding when to speed and how to stop, all without any manual. :D

+

: I did fall a few(read more than a few) times too.

+

: What came out of the process to me, is one very important life lesson: ''to keep balance, we must look forward and continue moving.''

'''Is there anything else we should have asked you or anything else that we should know that might make us like you or your project more?'''

−

: ~~Coming Soon~~

+

: Yes,

+

:* I did learn a lot in the last 6 weeks. From wikitext markup to Mediawiki API, pandoc, sphinx, reStructuredText and a bunch of other stuff. I had not even heard about most of these technologies before coming across this project. So, '''thank you''' for the opportunity :)

+

:* I've always tried to prove my worth by action. The script is completely working and maybe just needs some refinement.

+

:: Proof: 4 of the 345 pages have already been migrated and thus I know the intricate difficulties a lot better than my competitors(why? because well, I actually did the work)

+

:* Personally, the field of education is very close to my heart. I help out local middle school students to learn basic Computer Science concepts using simple flowcharts and other intuitive stuff, in my hometown(a small town with inadequate quality learning options)

+

:: and thus for the common goal, I believe I'll continue to work with the Sugar Labs organization and you all in the coming future.

+

'' Feel free to discuss your opinion about everything mentioned above via developer list thread''

+

''Thanks,''

+

''Rudra Sadhu''

Rdrsadhu

154

edits