Assigned: ICDevs.org Bounty #46 - Candy Library Documentation and Refactoring - $2,000

Developers Bounties
1

Candy Library Documentation and Refactoring - Motoko - #46

Current Status: Discussion

  • Discussion (01/09/2023)
  • Ratification: (01/09/2023)
  • Open for application: (01/09/2023)
  • Assigned
  • In Review
  • Closed

Official Link

Bounty Details

  • Bounty Amount: $2,000 USD of ICP at award date.
  • ICDevs.org Bounty Acceleration: For each 1 ICP sent to ece0c010e460e7a3094f207c984b37d961387186f45bfcec06be228330a62306, ICDevs.org will add .25 ICP to this issue and .75 ICP to fund other ICDevs.org initiatives.
  • Project Type: Individual
  • Opened: 01/09/2023
  • Time Commitment: Weeks
  • Project Type: Library
  • Experience Type: Intermediate - Motoko; Intermediate - Rust; Intermediate - JS;

Description

Candy Library provides an extensible set of types for the basic motoko types.

You will update GitHub - icdevs/candy_library: Library for Converting Types and Creating Workable Motoko Collections with documentation and examples for each function in the library.

The 2.0 branch needs to be deleted.

The library needs to be set up for Vessel and Mops.

Add missing conversion types.

Update the Buffer Implementation to the latest base library.

This bounty gives the opportunity to

  • learn about Motoko
  • learn about Candy Library

To apply for this bounty you should:

  • Include links to previous work writing tutorials and any other open-source contributions(ie. your github).
  • Include a brief overview of how you will complete the task. This can include things like which dependencies you will use, how you will make it self-contained, the sacrifices you would have to make to achieve that, or how you will make it simple. Anything that can convince us you are taking a thoughtful and expert approach to this design.
  • Give an estimated timeline on completing the task.
  • Post your application text to the Bounty Thread

Selection Process

The ICDevs.org developerā€™s advisors will propose a vote to award the bounty and the Developer Advisors will vote.

Bounty Completion

Please keep your ongoing code in a public repository(fork or branch is ok). Please provide regular (at least weekly) updates. Code commits count as updates if you link to your branch/fork from the bounty thread. We just need to be able to see that you are making progress.

The balance of the bounty will be paid out at completion.

Once you have finished, please alert the dev forum thread that you have completed work and where we can find that work. We will review and award the bounty reward if the terms have been met. If there is any coordination work(like a pull request) or additional documentation needed we will inform you of what is needed before we can award the reward.

Bounty Abandonment and Re-awarding

If you cease work on the bounty for a prolonged(at the Developer Advisory Boardā€™s discretion) or if the quality of work degrades to the point that we think someone else should be working on the bounty we may re-award it. We will be transparent about this and try to work with you to push through and complete the project, but sometimes, it may be necessary to move on or to augment your contribution with another resource which would result in a split bounty.

Funding

The bounty was generously funded by the DFINITY Foundation. If you would like to turbocharge this bounty you can seed additional donations of ICP to ece0c010e460e7a3094f207c984b37d961387186f45bfcec06be228330a62306. ICDevs will match the bounty $40:1 ICP for the first 25 ICP out of the DFINITY grant and then 0.25:1. All donations will be tax deductible for US Citizens and Corporations. If you send a donation and need a donation receipt, please email the hash of your donation transaction, physical address, and name to donations@icdevs.org. More information about how you can contribute can be found at our donations page.

FYI: General Bounty Process

Discussion

The draft bounty is posted to the DFINITY developerā€™s forum for discussion

Ratification: (01/09/2023)

The developer advisorā€™s board will propose a bounty be ratified and a vote will take place to ratify the bounty. Until a bounty is ratified by the Dev it hasnā€™t been officially adopted. Please take this into consideration if you are considering starting early.

Open for application

Developers can submit applications to the Dev Forum post. The council will consider these as they come in and propose a vote to award the bounty to one of the applicants. If you would like to apply anonymously you can send an email to austin at icdevs dot org or sending a PM on the dev forum.

Assigned

A developer is currently working on this bounty, you are free to contribute, but any splitting of the award will need to be discussed with the currently assigned developer.

In Review

The Dev Council is reviewing the submission

Awarded

The award has been given and the bounty is closed.

Other ICDevs.org Bounties

1 Like
2

Hi @skilesare!

I am new here and would like to take up this task. I havenā€™t worked with Motoko before but I believe this is a great starter project.

Background

5+ YOE in C++
1 YOE in Rust
Picked up Scala recently
Primarily a Compiler Engineer but recently started looking into Blockchains
Github: darkdrag00nv2

Active in the Ergo ecosystem with contributions to the Sigmastate-Interpreter project:

  • isEmpty support in the compiler - PR
  • ContractTemplate support in the SDK - Under review PR

Plan

I am a little hesitant to give a strict timeline since I am new to Motoko but the following represents a best-effort plan I have:

  • Read the candy_library codebase using the Motoko docs for reference - In progress
  • Add documentation and examples for each function - 1 week
  • Add any missing conversion types & misc - 1 week

Thanks for your consideration!

3

Iā€™d love for you to give it a try.

Iā€™ll submit itā€¦you should be able to get started.

Note: Iā€™ve recently started a bit of a refactor with stable types. Iā€™ll loop you in on it.

1 Like
4

Thank you.

The progress can be tracked on this PR - Refactor & Document the library by darkdrag00nv2 Ā· Pull Request #14 Ā· icdevs/candy_library Ā· GitHub

5

Iā€™ve pushed GitHub - icdevs/candy_library at 0.2.0

Iā€™ve moved from Buffer to Stable Buffer for stability so a more appropriate task for the bounty might be to add the new Buffer functions from the 8.3 base library into the Stable buffer.

@icme did this original work and I think it is a fairly straightforward conversion and you get to learn a lot about the difference between functional and OO programming. They added a bunch of convenience methods to buffer in base and they would be nice to have here as well.

1 Like
6

Update

The progress can be tracked on the PR but posting the summary here for ease of tracking.

So far

Documentation and examples are almost done. Only functions inside workspace.mo are remaining.
Added a small GitHub Actions CI setup to at least compile the library on each PR

Next steps

Finish documenting workspace.mo as well
Add new buffer functions from the 8.3 base library into the Stable Buffer implementation
[Stretch goal] Add missing conversion types

Questions

@skilesare I have two questions:

The library is already setup with Vessel. Also, it seems like only one of them can be used at a time since they both require setting itself as the packtool. Perhaps we could keep separate branches.

I didnā€™t get this step. Can you elaborate please?

7

I merged your stuff and just pushed some more changes:

  • Got rid of the Buffer static warning
  • Changed CandyValueUnstable to CandyValueShared at @ZhenyaUsenkoā€™s suggestion. This is annoying but technically correct as opposed to the other name. Shared values can be stored in stable and avoid pre-post upgrade handling, but canā€™t be returned.
  • Removed the legacy aramakme licensing stuff.

Next Steps:

  • I already removed the old 2.0 branch and replaced it with this one, so disregard it.
  • Interesting about mops, vessel. Maybe @Gekctek and @rvanasa can give us some insights on how the next gen is coming together and if mops is going to take over or if vessel is going to be improved.
1 Like
8

@darkdrag00n I would just choose one vs doing both. I was trying both but it doesnā€™t really work.
I would suggest doing MOPS because it allows you to publish to MOPS (https://mops.one/) so that its essentially indexed and searchable and usable with names vs urls.
But MOPS lets you just point to a library at a git url, so it doesnā€™t ultimately matter for a MOPS user, just harder to find libraries
Also im using the MOPS testing library so I dont need to compile to wasm manually or run a wasm manually

Here is what Im using for a template for my libraries

and here is my latest library that can also be used as reference

4 Likes
9

@darkdrag00n I just pushed a big update that changes the names of a ton of things.

Basically:

ValueUnstable ā†’ Candy (ā€˜unstableā€™ used to mean usableā€¦now that the stable types are in, this is the norm
Value ā†’ CandyShared
valueToX ā†’ candySharedToX
valueUnstableToX ā†’ candyToX

Hopefully, this will read a bit better now to people that are unfamiliar to the library. You should really only need valueShared when dumping a return from an actor.

Let me know your thoughts on this. We can always move to something else if it makes sense.

1 Like
10

Although is not well documented yet, it is worth considering that the formatting for the comments used as headers of methods could be updated to be proper ā€œMotokodocā€. Hereā€™s an explanation of Motokodoc and an example.

In particular, IIRC the // will not be picked up when running moc doc when generating docs as well.

Iā€™ve seen the @param/returns used when writing Motokodoc for methods but iirc it is not (yet) a feature.

2 Likes
11

@skilesare A small update. My laptop died, Iā€™ll get it repaired over the weekend and will resume work from Monday onwards next week.

Thanks for your patience.

12

My laptop is back working now. I am resuming the work.

@icaten Thanks for sharing. Do note that Iā€™ve used /// instead of //. Example in the candy library. The /// does get picked up by the moc doc.

That also seems to be inline with what the Motoko base library does - Example.

13

@skilesare There are many functions in 8.3 base library which are not in Stable buffer. It would be non-trivial to port all of them. Do you have a list of few top priority ones which we need for candy_library?

Iā€™ve ported 3 functions as part of this PR - Implement remove, reverse & fromVarArray in StableBuffer by darkdrag00nv2 Ā· Pull Request #6 Ā· canscale/StableBuffer Ā· GitHub

Will add more based on your recommendations.

14

Maybe @claudio can comment. I think he either wrote most of them or knows who did. @icme did the initial work, and I think there was some trick to it. Basically I think you just need to add the object as the first var of each one and then put buffer. in front of most of the items. Iā€™ll try to take a look in a bit.

15

Reviewed the PR - sorry for the delay!

Happy to accept any and all contributions to extend the StableBuffer to achieve parity with the wealth of functions that the new base Buffer class has.

Hopefully it shouldnā€™t take too long to add more functions, but agree that since there are 2500+ lines of code in the new buffer vs. ~175 in StableBuffer thereā€™s quite a bit to add.

Luckily, @kentosugama did a great job of adding both functions and extensive tests.

@skilesare Maybe itā€™s a good idea to pick/prioritize the functions youā€™d like most to be moved over. Iā€™d estimate moving the full suite over might take a day or two of work, plus a day or two for me to review and check correctness. Iā€™d honestly prefer many small PRs instead of one large one (easier to review and perform some quality control).

1 Like
16

Let me move this to a new bounty. Weā€™ll just take the buffer part out of this one.

1 Like
17

@skilesare Sure or if possible, you can increase the reward on this one as well as I would like to work on it. Iā€™ve already opened 2 PRs for it. Either choice works.

Also, please review Part 2: Refactor & Document the library by darkdrag00nv2 Ā· Pull Request #15 Ā· icdevs/candy_library Ā· GitHub.

@icme Iā€™ve updated Implement remove, reverse & fromVarArray in StableBuffer by darkdrag00nv2 Ā· Pull Request #6 Ā· canscale/StableBuffer Ā· GitHub based on your review comments. Iā€™ve also opened another PR implementing 3 more functions - Implement capacity, insert and insertBuffer by darkdrag00nv2 Ā· Pull Request #8 Ā· canscale/StableBuffer Ā· GitHub

18

Weā€™ll do a separate on for buffer and Youā€™ll have first right of refusal if it gets approved.

1 Like
19

Looks good, reviewed and commented on the issue you opened here Why does StableBuffer<X> store [var X] instead of [var ?X]? Ā· Issue #7 Ā· canscale/StableBuffer Ā· GitHub.

20

@skilesare
Two PRs that need your attention

  1. Part 2: Refactor & Document the library by darkdrag00nv2 Ā· Pull Request #15 Ā· icdevs/candy_library Ā· GitHub ā€“ Implements missing conversion types, cleans up the README and a minor bug fix
  2. Setup Mops & Publish to GitHub Pages by darkdrag00nv2 Ā· Pull Request #16 Ā· icdevs/candy_library Ā· GitHub ā€“ Add support for Mops & publishing docs to GH pages

With StableBuffer part out of the scope of this bounty, the only remaining piece now is to document workspace.mo which Iā€™ll do tomorrow.