Developer Guideline

Before starting

Hey there developers! We're excited to have you on board with Numbers. As we continue to grow and evolve, it can be tough to keep all of our documentation up-to-date. If you come across any errors or outdated information in this document, don't hesitate to bring it to the attention of your fellow team members. By working together to keep our documentation accurate, we can make the experience better for everyone - including the maintainer of this document (that's me!) and future newcomers. It's all about collaboration and moving fast. Let's make this journey with Numbers an awesome one!

Numbers brand values

Brand values are essential for us as they serve as a foundation for the identity and reputation of Numbers Protocol. Brand Values define our purpose and mission, and guide decision-making and actions. It is important that you are fully aware of the brand values before start the development journey.

Culture

Be Proactive, Not Reactive

As a developer at Numbers, it's important to have a proactive mindset. By understanding and predicting potential future situations, we can make the best decisions and take charge of our own progress. On the other hand, a reactive mindset can leave us feeling unprepared and constantly playing catch-up.

Product-Dev Paradox

The product development focus is dynamic in every sprint depending on the product status. Please read the definitions and guidelines.

Working Hours

In terms of working hours, we encourage you to read "Toward A Better Remote Working Environment" and to provide your working hours to ${hr}, as well as adding them to your Slack profile. This will help your colleagues have the right expectations of when you'll be available to respond to messages. During your working hours, please aim to respond to Slack messages within 15 minutes and keep your Slack status updated to reflect your current status.

Three-Month Probation

Please note that as a new team member, you will be on a three-month probation period. During this probation period, your ${mento}r will be available to support you and answer any questions you may have. We value teamwork and collaboration, so we ask that you actively work to be a good team player and contribute to the positive work environment we have here at Numbers.

At the end of the probation period, all product members will evaluate you with the question "Do you feel it is wonderful to work with this new member?" To pass the probation period, you must receive "yes" from ALL colleagues working with you. We have high expectations for our team members and want to ensure that everyone feels comfortable and supported in our working environment.

Roles

${admin}	Bofu <bofu AT numbersprotocol.io>
${mentor}	The one helping a newcomer in the probation and is assigned in the welcome email.
${hr}	Joanne <hr AT numbersprotocol.io>
${techlead}	Bofu <bofu AT numbersprotocol.io>

Communication

Slack

For internal communication. Here are the engineering-related channels, and you can free explore others to meet more people:

Channel	Description
#zeroth	Chatting (and trash talks, of course)
#marvin42	Engineer team’s channel. You can always feel free and safe to ask questions here.
#dev-nse	Discussion related to Numbers Search Engine
#dev-network-action	Discussion related to Network Action
#dev-capture-app	Discussion related to Capture App
#dev-protocol	Discussion related to assetization activities, nit, etc.
#dev-numbers-api	Discussion related to API development.
#product	Main product channel.
#product-kuai-kuai	Channel that tracks Critical product downtime.
#reminder-releases	Release channel.
#qa-pm	Main channel to communicate with QA.
#bubble	Discussion related to Bubble Apps.
#dev-infrastructure	Any questions about infrastructures (e.g. GC, network, etc.)

You can find more public channels by clicking the “Channels” on the left-side panel on Slack.

Asana

Sprint goals and tasks are available in the Product Tribe team. Tracking tasks in Asana is crucial for the success of our products. It ensures that all team members are aware of their responsibilities, timelines, and progress.

You are responsible for keeping tasks up-to-date and making sure there are no overdue tasks in Asana. This plays an essential role for effective project management and team collaboration.

Meetings

Please subscribe Numbers Scrum calendar and follow the scrum schedule. If you cannot access the Numbers Scrum calendar, contact ${admin}.

Type	Location	Time	Preparation
Daily sync-up	Slack huddle at #marvin42	13:00 - 13:20 GMT+8 Every Tue/Thu	Share your progress on Slack
Sprint demo	Slack huddle at #product	16:50-18:00 GMT+8 Every Wed	Record demo video by 14:30 GMT+8
Weekly meeting	Slack huddle at #product	13:00-13:40 GMT+8 Every Mon	Share your weekly goals and tasks

Table: Product team meeting schedule

Meeting Tips

• Always try to share from the angle: what matters to the team?

• Keep your camera open.

• Mute your microphone if you are not speaking.

Product sprint

At Numbers, we adopt the Scrum framework, which is an agile framework for project management and product development. It is designed to help teams work together more effectively and efficiently. A sprint is a time-boxed period, usually two weeks. The development goals are set in the Product Roadmap project.

It is important that everyone is being agile because it allows teams to be more responsive to the fast-paced changes in the market, and to deliver products and services that better meet the needs of their customers. Read Numbers Scrum for more details.

Documentation

Proper documentation of technical notes is vital for the development of any software or application. It ensures that the knowledge and processes used in the creation of the product are recorded and easily accessible to the team. This not only improves efficiency and productivity but also helps to mitigate the risk of knowledge loss due to turnover or other unforeseen circumstances. ALWAYS make sure your have properly documented notes, steps, thoughts during the development.

GitHub

We use GitHub to store and manage source codes. Sharing your personal account with ${admin}. Make sure README of the repositories are up-to-date.

GitBook

As Numbers is a Web3 project, transparency is important. You should be able to find most developer guidelines on the Gitbook of Numbers Protocol and Capture. Due to the security concerns, some materials and source codes are permission protected. Check the Permission Protected page for the links and log in with your Numbers email.

Google Workspace

We also use Google Workspace file (doc, spreadsheet, slides, etc.) to exchange ideas and thoughts in the remote-working environment. When creating Google Workspace file, ensure that it is under the Marvin directory with proper access permission.

Old Dev Doc

Some useful information is not yet migrated to Gitbook. Check numbers-dev-doc for technical notes written by the team.

External Services

The list of services related to development. If you need to access a shared account (the account field is not empty), contact ${admin} to get the access permission.

Development Tips

Development

1. We adopt the development model of GitHub Flow (simplified Gitflow [1, 2]). Please also read Git Usage Guidelines. The differences are: We add fix-* branch for an essential fix if its scope is large and needs a review. The rule is the same as feature-*.

2. We use Semantic Versioning and Conventional Commits.

3. If you use Visual Studio Code, highly recommend installing the Code GPT (try the text-davinci-003 model if you're not familiar with Code GPT yet) and Copilot extensions.

4. Before you send your pull request for code review, consider sharing your updates with ChatGPT and checking for any feedback.

5. Dev Status flow

Release

As a developer, it's important to make sure that you've thoroughly tested your code before releasing it to production. This includes running lint checks, unit tests, and end-to-end tests to ensure that everything is working as expected.

The Product release flow may vary depending on the specific product or category, but these tests are always a crucial step in the process. Remember to double-check your work and make sure that you've covered all the necessary user stories for each task before moving on to the next step of the release flow.

1. Release Guidelines

2. Release and testing process (QA document)

3. Testing flow

Process Discussion

For product process related discussions, please leverage Miro -> Product Dev -> Process.

• Dev discussion => individual product Miro (capture app, storage backend, nse, etc)

• Process discussion (where QA is also involved) => process Miro

WORKAROUND comments

Before applying a workaround, you need to get approval from ${techlead}.

Workaround comment format, Python template:

# WORKAROUND: <issue link>
# 	<workaround-purpose>

Example:

# WORKAROUND: https://gitlab.com/DT42/marvin42/dlbox-release/issues/45
# Prevent snapshot from creating orphans after being restarted

Coding style

if modify_external_project
    follow_external_project_style
else
    follow_google_style_guides  # 

Google Style Guides

Timing to add comments instead of deleting codes

1. At the early stage of feature development if the codes are likely to be re-used or referenced.

2. We need to disable a feature temporarily and will re-enable it soon.

Under these conditions, we might only comment out the codes and keeps them:

Software engineering

Software Engineering at Google is practical and worth reading.

Android

Android App Asset Best Practice

RESTful API Design

簡明 RESTful API 設計要點 (Chinese)

Publish packages

PyPI

Cheat sheet to upload Python packages to PyPI.

# Download and setup access token
# Contact admin if you do not have the access permission
$ cp <download-dir>/pypirc ~/.pypirc
$ chmod 600 ~/.pypirc

# Install uploading tool
$ python3 -m pip install --user --upgrade twine

# Build packages
$ python3 setup.py sdist bdist_wheel

# Upload to testing repository
# Username and password are in ~/.pypirc
$ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Enter your username: __token__
Enter your password:

# Install and test package by using testing repository
$ python3 -m pip install --index-url https://test.pypi.org/simple/ <package-name>
$ python3 
>>> import <package-name>
$ python3 -m pip uninstall <package-name>

# Upload to standard repository
$ python3 -m twine upload dist/*

# Install by using standard repository
$ python3 -m pip install <package-name>

More details: Packaging Python Projects

To get the Numbers account, please contact the ${admin}.

NPM

Cheat sheet to upload JavaScript packages to NPM.

# Contact admin if you do not have the access permission
$ npm login
$ npm publish --access public

More details: Creating and publishing an Org scoped package

Starting a new journey

If you are moving on from Numbers and embarking on a new chapter in your career, this guide will assist you in passing on your valuable knowledge and skills to the team. It is important for us to ensure a smooth transition and maintain continuity of our projects. We appreciate the hard work and dedication you have put into the company and wish you all the best in your future endeavors.

1. Confirm who is your hand-over partner. Ask ${mentor} if you do not know who the partner is.

2. Record videos on Claap

The videos should cover the following topics

• How to set up the working environment

• Debugging tips

• Status of the releases to QA

• Send PR (or deploy to the Testing environment)

• Steps to manage the infrastructure services you are owning, for example,

• Slack bot you created

3. Transfer the ownership of the services you are owning to your partner.

4. Open a hand-over task on Asana.

For every video, add a subtask containing the video link, and assign your partner and ${mentor} as the collaborators.Ping your partner to review the videos and help your partner to complete all the subtasks.

5. Get a confirmation from ${mentor} that your hand-over is completed.

Then you can complete your hand-over task. Congratulations!