tfgrid/info_tfgrid_manual
28
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

...

Browse Source
This commit is contained in:
despiegk
2024-02-23 06:07:41 +03:00
commit a83f4cd5e8
1963 changed files with 56869 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
tosort/contribute/PULL_REQUEST_TEMPLATE.md Normal file
View File

@@ -0,0 +1,18 @@
### Description
Describe the changes introduced by this PR and what does it affect
### Changes
List of changes this PR includes
### Related Issues
List of related issues
### Checklist
- [ ] Tests included
- [ ] Build pass
- [ ] Documentation
- [ ] Code format and docstring

29
tosort/contribute/bug_report.md Normal file
View File

@@ -0,0 +1,29 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
## Describe the bug
A clear and concise description of what the bug is.
## To Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## Expected behavior
A clear and concise description of what you expected to happen.
## Screenshots
If applicable, add screenshots to help explain your problem.

318
tosort/contribute/code_conduct.md Normal file
View File

@@ -0,0 +1,318 @@
<h1> Code of Conduct</h1>
<h2>Table of Contents</h2>
- [Introduction: Collaboration Manifest](#introduction-collaboration-manifest)
- [Code of Conduct](#code-of-conduct)
- [Forum \& Chat Rules](#forum--chat-rules)
- [Moderation Rights](#moderation-rights)
- [Contribution](#contribution)
- [Keep It Simple and Relevant](#keep-it-simple-and-relevant)
- [Content Verification Guidelines](#content-verification-guidelines)
- [Freedom of Speech.](#freedom-of-speech)
- [Contribution Guidelines](#contribution-guidelines)
- [This is a Civilized Place for Public Discussion](#this-is-a-civilized-place-for-public-discussion)
- [Improve the Discussion](#improve-the-discussion)
- [Be Agreeable, Even When You Disagree](#be-agreeable-even-when-you-disagree)
- [Your Participation Counts](#your-participation-counts)
- [If You See a Problem, Flag It](#if-you-see-a-problem-flag-it)
- [Always Be Civil](#always-be-civil)
- [Keep It Tidy](#keep-it-tidy)
- [Post Only Your Own Stuff](#post-only-your-own-stuff)
- [Powered by You](#powered-by-you)
- [Terms of Service](#terms-of-service)
- [Terms of Service (TOS)](#terms-of-service-tos)
- [Important Terms](#important-terms)
- [Your Permission to Use the Forum)](#your-permission-to-use-the-forum)
- [Conditions for Use of the Forum](#conditions-for-use-of-the-forum)
- [Acceptable Use](#acceptable-use)
- [Content Standards](#content-standards)
- [Enforcement](#enforcement)
- [Your Account](#your-account)
- [Your Content](#your-content)
- [Your Responsibility](#your-responsibility)
- [Disclaimers](#disclaimers)
- [Limits on Liability](#limits-on-liability)
- [Feedback](#feedback)
- [Termination](#termination)
- [Disputes](#disputes)
- [General Terms](#general-terms)
- [Contact](#contact)
- [Changes](#changes)
***
# Introduction: Collaboration Manifest
FreeFlow nation created this collaboration manifest which can be freely used by any organization who finds them useful. If you would like to see any changes to this document please email to **info@freeflownation.org**.
We at ThreeFold want to follow these guidelines.
This document has been created honoring the [FreeFlow Nation Manifesto](https://www.freeflownation.org/manifesto.html).
# Code of Conduct
## Forum & Chat Rules
We are committed to making participation a harassment-free experience for everyone, regardless of level of experience, gender, gender identity or expression, sexual orientation, disability, personal appearance, race, ethnicity, age, religion, or nationality.
Examples of unacceptable behavior include, but are not limited to:
* Use of sexualized language or imagery
* Personal attacks
* Trolling or insulting/derogatory comments
* Public or private harassment
* Publishing private information without explicit permission (e.g. physical or electronic address)
## Moderation Rights
Content moderators have the right and responsibility to remove, edit, or reject all posts, comments, and other contributions that are not aligned to this Code of Conduct. They may also suspend or ban any forum member for behaviors that they deem inappropriate, threatening, offensive, or harmful.
By adopting this Code of Conduct, moderators commit themselves to fairly and consistently applying these principles to every aspect of managing this community. Moderators who do not follow or enforce the Code of Conduct may be permanently removed from the moderation team.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by flagging the post or comment in question. All complaints will be reviewed and investigated and will result in a response deemed both necessary and appropriate to the circumstances. Moderators are obligated to maintain confidentiality regarding the identity of the reporting party.
The forum is a place where we bring people together that share the same values and want to make the world a better place. Positive feedback is well appreciated but must always stay respectful and helpful. Moderators thus have the right to remove any posts spreading negativity and/or attacking the project and its founders.
## Contribution
We welcome everyone to contribute and thank you for your content contribution.
Content can be chat, questions, answers, blogs, articles, knowledge base information, tutorials, …
The more people collaborate the more relevant set of information will be created.
Creating content constitutes your agreement to release submitted content as public domain ([CC0 10 4](https://creativecommons.org/publicdomain/zero/1.0/)).
## Keep It Simple and Relevant
Overload of information is maybe even worse as not enough information.
Please keep your discussions and contributions information-rich. If your signal-to-noise ratio gets too low, you will be muted or banned from the forum or relevant chat. This is up to the discretion of ThreeFold moderators.
## Content Verification Guidelines
We believe it’s in the best interest of our community to know the origin and authenticity of any information contributed. We want to do everything possible to verify the authenticity of the content created (e.g. messages, knowledge-base, chats, etc.). As such it’s our right to block a contributor from creating any content if identity cannot be verified.
## Freedom of Speech.
We believe in freedom of speech as long as it’s not in contradiction with our Content Verification Guidelines.
# Contribution Guidelines
## This is a Civilized Place for Public Discussion
Please treat this discussion forum with the same respect you would a public park. We, too, are a shared community resource — a place to share skills, knowledge and interests through ongoing conversation.
These are not hard and fast rules, merely guidelines to aid the human judgment of our community and keep this a clean and well-lighted place for civilized public discourse.
## Improve the Discussion
Help us make this a great place for discussion by always working to improve the discussion in some way, however small. If you are not sure your post adds to the conversation, think over what you want to say and try again later.
The topics discussed here matter to us, and we want you to act as if they matter to you, too. Be respectful of the topics and the people discussing them, even if you disagree with some of what is being said.
One way to improve the discussion is by discovering ones that are already happening. Spend time browsing the topics here before replying or starting your own, and you’ll have a better chance of meeting others who share your interests.
## Be Agreeable, Even When You Disagree
You may wish to respond to something by disagreeing with it. That’s fine. But remember to criticize ideas, not people. Please avoid any of the following:
* Name-calling
* Ad hominem attacks
* Responding to a post’s tone instead of its actual content
* Knee-jerk contradiction
Instead, provide reasoned counter-arguments that improve the conversation.
## Your Participation Counts
The conversations we have here set the tone for every new arrival. Help us influence the future of this community by choosing to engage in discussions that make this forum an interesting place to be — and avoiding those that do not.
The forum we use (Discourse) provides tools that enable the community to collectively identify the best (and worst) contributions: bookmarks, likes, flags, replies, edits, and so forth. Use these tools to improve your own experience, and everyone else’s, too.
Let’s leave our community better than we found it.
## If You See a Problem, Flag It
Moderators have special authority: they are responsible for this forum, but so are you. With your help, moderators can be community facilitators, not just janitors or police.
When you see bad behavior, don’t reply. It encourages bad behavior by acknowledging it, consumes your energy, and wastes everyone’s time. Just flag it. If enough flags accrue, action will be taken, either automatically or by moderator intervention.
In order to maintain our community, moderators reserve the right to remove any content and any user account for any reason at any time. Moderators do not preview new posts: the moderators and site operators take no responsibility for any content posted by the community.
## Always Be Civil
Nothing sabotages a healthy conversation like rudeness:
* Be civil. Don’t post anything that a reasonable person would consider offensive, abusive, or hate speech.
* Keep it clean. Don’t post anything obscene or sexually explicit.
* Respect each other. Don’t harass or grief anyone, impersonate people, or expose their private information.
* Respect our forum. Don’t post spam or otherwise vandalize the forum.
These are not concrete terms with precise definitions — avoid even the appearance of any of these things. If you’re unsure, ask yourself how you would feel if your post was featured on the front page of the New York Times.
This is a public forum, and search engines index these discussions. Keep the language, links, and images safe for family and friends.
## Keep It Tidy
Make the effort to put things in the right place, so that we can spend more time discussing and less time cleaning up.
In brief:
* Don’t start a topic in the wrong category.
* Don’t cross-post the same thing in multiple topics.
* Don’t post no-content replies.
* Don’t divert a topic by changing it midstream.
* Don’t sign your posts — every post has your profile information attached to it.
* Rather than posting “+1” or “Agreed”, use the Like button. Rather than taking an existing topic in a radically different direction, use Reply as a Linked Topic.
## Post Only Your Own Stuff
You may not post anything digital that belongs to someone else without permission. You may not post descriptions of, links to, or methods for stealing someone’s intellectual property (e.g. software, video, audio, images, etc.), or for breaking any other law.
## Powered by You
This site is operated by your friendly local staff and you, the community. If you have any further questions about how things should work here, open a new topic in the site feedback category and let’s discuss! If there’s a critical or urgent issue that can’t be handled by a meta topic or flag, contact us via the support live chat.
## Terms of Service
Yes, legalese is boring, but we must protect ourselves – and by extension, you and your data – against unfriendly folks. We have a Terms of Service describing your (and our) behavior and rights related to content, privacy, and laws. To use this service, you must agree to abide by our TOS. See below for more information on this.
# Terms of Service (TOS)
These terms include a number of important provisions that affect your rights and responsibilities, such as the disclaimers in Disclaimers, limits on the company’s liability to you in Limits on Liability, your agreement to cover the company for damages caused by your misuse of the forum in Responsibility for Your Use, and an agreement to arbitrate disputes in Disputes.
Please read:
To use this forum, or any other collaboration/communication tool of ThreeFold you must agree to these terms with threefold, the company that runs the forum or any other tool (FreeFlow Pages and others).
The company may offer other products and services, under different terms. These terms apply only to use of the forum.
## Important Terms
These terms include a number of important provisions that affect your rights and responsibilities, such as the disclaimers in [Disclaimers](#disclaimers), limits on the company’s liability to you in [Limits on Liability](#limits-on-liability), your agreement to cover the company for damages caused by your misuse of the forum in [Responsibility for Your Use](#your-responsibility), and an agreement to arbitrate disputes in [Disputes](#disputes).
## Your Permission to Use the Forum)
Subject to these terms, the company gives you permission to use the forum. Everyone needs to agree to these terms to use the forum.
## Conditions for Use of the Forum
Your permission to use the forum is subject to the following conditions:
1. You must be at least thirteen years old.
2. You may no longer use the forum if the company contacts you directly to say that you may not.
3. You must use the forum in accordance with [Acceptable Use](#acceptable-use) and [Content Standards](#content-standards).
## Acceptable Use
1. You may not break the law using the forum.
2. You may not use or try to use another’s account on the forum without their specific permission.
3. You may not buy, sell, or otherwise trade in user names or other unique identifiers on the forum.
4. You may not send advertisements, chain letters, or other solicitations through the forum, or use the forum to gather addresses or other personal data for commercial mailing lists or databases.
5. You may not automate access to the forum, or monitor the forum, such as with a web crawler, browser plug-in or add-on, or other computer program that is not a web browser. You may crawl the forum to index it for a publicly available search engine, if you run one.
6. You may not use the forum to send e-mail to distribution lists, newsgroups, or group mail aliases.
7. You may not falsely imply that you’re affiliated with or endorsed by the company.
8. You may not hyperlink to images or other non-hypertext content on the forum on other webpages.
9. You may not remove any marks showing proprietary ownership from materials you download from the forum.
10. You may not show any part of the forum on other websites with \<iframe\>.
11. You may not disable, avoid, or circumvent any security or access restrictions of the forum.
12. You may not strain infrastructure of the forum with an unreasonable volume of requests, or requests designed to impose an unreasonable load on information systems underlying the forum.
13. You may not impersonate others through the forum.
14. You may not encourage or help anyone in violation of these terms.
## Content Standards
1. You may not submit content to the forum that is illegal, offensive, or otherwise harmful to others. This includes content that is harassing, inappropriate, or abusive.
2. You may not submit content to the forum that violates the law, infringes anyone’s intellectual property rights, violates anyone’s privacy, or breaches agreements you have with others.
3. You may not submit content to the forum containing malicious computer code, such as computer viruses or spyware.
4. You may not submit content to the forum as a mere placeholder, to hold a particular address, user name, or other unique identifier.
5. You may not use the forum to disclose information that you don’t have the right to disclose, like others’ confidential or personal information.
## Enforcement
The company may investigate and prosecute violations of these terms to the fullest legal extent. The company may notify and cooperate with law enforcement authorities in prosecuting violations of the law and these terms.
The company reserves the right to change, redact, and delete content on the forum for any reason. If you believe someone has submitted content to the forum in violation of these terms, [contact us immediately](#contact).
## Your Account
You must create and log into an account to use some features of the forum.
To create an account, you must provide some information about yourself. If you create an account, you agree to provide, at a minimum, a valid e-mail address, and to keep that address up-to-date. You may close your account at any time by e-mailing **info@threefold.io**.
You agree to be responsible for all action taken using your account, whether authorized by you or not, until you either close your account or notify the company that your account has been compromised. You agree to notify the company immediately if you suspect your account has been compromised. You agree to select a secure password for your account, and keep it secret.
The company may restrict, suspend, or close your account on the forum according to its policy for handling copyright-related takedown requests, or if the company reasonably believes that you’ve broken any rule in these terms.
## Your Content
Nothing in these terms gives the company any ownership rights in intellectual property that you share with the forum, such as your account information, posts, or other content you submit to the forum. Nothing in these terms gives you any ownership rights in the company’s intellectual property, either.
Between you and the company, you remain solely responsible for content you submit to the forum. You agree not to wrongly imply that content you submit to the forum is sponsored or approved by the company. These terms do not obligate the company to store, maintain, or provide copies of content you submit, and to change it, according to these terms.
Content you submit to the forum belongs to you, and you decide what permission to give others for it. But at a minimum, you license the company to provide content that you submit to the forum to other users of the forum. That special license allows the company to copy, publish, and analyze content you submit to the forum.
When content you submit is removed from the forum, whether by you or by the company, the company’s special license ends when the last copy disappears from the company’s backups, caches, and other systems. Other licenses you apply to content you submit, such as [Creative Commons](https://creativecommons.org/) licenses, may continue after your content is removed. Those licenses may give others, or the company itself, the right to share your content through the forum again.
Others who receive content you submit to the forum may violate the terms on which you license your content. You agree that the company will not be liable to you for those violations or their consequences.
## Your Responsibility
You agree to indemnify the company from legal claims by others related to your breach of these terms, or breach of these terms by others using your account on the forum. Both you and the company agree to notify the other side of any legal claims for which you might have to indemnify the company as soon as possible. If the company fails to notify you of a legal claim promptly, you won’t have to indemnify the company for damages that you could have defended against or mitigated with prompt notice. You agree to allow the company to control investigation, defense, and settlement of legal claims for which you would have to indemnify the company, and to cooperate with those efforts. The company agrees not to agree to any settlement that admits fault for you or imposes obligations on you without your prior agreement.
## Disclaimers
You accept all risks of using the forum and content on the forum. As far as the law allows, the company and its suppliers provide the forum as is, without any warranty whatsoever.
The forum may hyperlink to and integrate forums and services run by others. The company does not make any warranty about services run by others, or content they may provide. Use of services run by others may be governed by other terms between you and the one running service.
## Limits on Liability
Neither the company nor its suppliers will be liable to you for breach-of-contract damages their personnel could not have reasonably foreseen when you agreed to these terms.
As far as the law allows, the total liability to you for claims of any kind that are related to the forum or content on the forum will be limited to $50.
## Feedback
The company welcomes your feedback and suggestions for the forum. See the [Contact](#contact) section below for ways to get in touch with us.
You agree that the company will be free to act on feedback and suggestions you provide, and that the company won’t have to notify you that your feedback was used, get your permission to use it, or pay you. You agree not to submit feedback or suggestions that you believe might be confidential or proprietary, to you or others.
## Termination
Either you or the company may end the agreement written out in these terms at any time. When our agreement ends, your permission to use the forum also ends.
The following provisions survive the end of our agreement: [Your Content](#your-content), [Feedback](#feedback), [Your Responsibility](#your-responsibility), [Disclaimers](#disclaimers), [Limits on Liability](#limits-on-liability), and [General Terms](#general-terms).
## Disputes
ascsac will govern any dispute related to these terms or your use of the forum.
You and the company agree to seek injunctions related to these terms only in state or federal court in city_for_disputes. Neither you nor the company will object to jurisdiction, forum, or venue in those courts.
Other than to seek an injunction or for claims under the Computer Fraud and Abuse Act, you and the company will resolve any dispute by binding American Arbitration Association arbitration. Arbitration will follow the AAA’s Commercial Arbitration Rules and Supplementary Procedures for Consumer Related Disputes. Arbitration will happen in city_for_disputes. You will settle any dispute as an individual, and not as part of a class action or other representative proceeding, whether as the plaintiff or a class member. No arbitrator will consolidate any dispute with any other arbitration without the company’s permission.
Any arbitration award will include costs of the arbitration, reasonable attorneys’ fees, and reasonable costs for witnesses. You and the company may enter arbitration awards in any court with jurisdiction.
## General Terms
If a provision of these terms is unenforceable as written, but could be changed to make it enforceable, that provision should be modified to the minimum extent necessary to make it enforceable. Otherwise, that provision should be removed.
You may not assign your agreement with the company. The company may assign your agreement to any affiliate of the company, any other company that obtains control of the company, or any other company that buys assets of the company related to the forum. Any attempted assignment against these terms has no legal effect.
Neither the exercise of any right under this Agreement, nor waiver of any breach of this Agreement, waives any other breach of this Agreement.
These terms embody all the terms of agreement between you and the company about use of the forum. These terms entirely replace any other agreements about your use of the forum, written or not.
## Contact
You may notify the company under these terms, and send questions to the company, at **info@threefold.io**.
The company may notify you under these terms using the e-mail address you provide for your account on the forum, or by posting a message to the homepage of the forum or your account page.
## Changes
The company last updated these terms on Aug, 2020, and may update these terms again. For updates that contain substantial changes, the company agrees to e-mail you, if you’ve created an account and provided a valid e-mail address. The company may also announce updates with special messages or alerts on the forum.
Once you get notice of an update to these terms, you must agree to the new terms in order to keep using the forum.

18
tosort/contribute/collaboration_toc.md Normal file
View File

@@ -0,0 +1,18 @@
<h1> Collaboration </h1>
Welcome to the *Collaboration* section of the ThreeFold Manual, the doorway to collaboration and creation on the organic ThreeFold ecosystem.
*All Aboard!*
ThreeFold strongly believes in the power of open-source projects and community-driven collaboration. Do you want to collaborate to the ThreeFold project?
<h2>Table of Contents</h2
- [How to Contribute](./contribute.md)
- [Development Process](./development_process.md)
- [Collaboration Tools](../collaboration_tools/collaboration_tools.md)
- [Circle Tool](../collaboration_tools/circle_tool.md)
- [Website Deployer](../collaboration_tools/website_tool.md)
- [Website Link Checker](../collaboration_tools/website_link_checker.md)
- [How to Test](../testing/testing_readme.md)
- [TestLodge](../testing/testlodge.md)

119
tosort/contribute/contribute.md Normal file
View File

@@ -0,0 +1,119 @@
<h1> How to Contribute to the Threefold Manual </h1>
<h2>Table of Contents</h2>
- [Quick Method: Create an Issue](#quick-method-create-an-issue)
- [Advanced Method: Create a Pull Request](#advanced-method-create-a-pull-request)
- [Main Steps to Add Content](#main-steps-to-add-content)
- [How to View the mdbook Locally](#how-to-view-the-mdbook-locally)
- [How to Install git and mdbook](#how-to-install-git-and-mdbook)
- [Markdown File Template (Optional)](#markdown-file-template-optional)
- [Questions and Feedback](#questions-and-feedback)
***
## Quick Method: Create an Issue
If you've found some issues or typos in the ThreeFold Manual, feel free to [create an issue on the ThreeFold Manual repository](https://github.com/threefoldtech/info_grid/issues) to let us know. We will then be able to fix it as soon as possible.
The steps are simple:
* Go to the [issues section of ThreeFold Manual](https://github.com/threefoldtech/info_grid/issues) repository on GitHub
* Click on `New Issue`
* Choose an appropriate title
* Explain briefly the issue you found
* Click `Submit New Issue`
***
## Advanced Method: Create a Pull Request
If you found an issue in the manual and you wish to fix the issue yourself, you can always fork the repository and propose the changes in a pull request. We present the main steps in this section as well as further details on how to proceed efficiently.
***
### Main Steps to Add Content
***
We present here the main steps to add content to the Threefold Manual by forking the repository [`threefoldtech/info_grid`](https://github.com/threefoldtech/info_grid) to your own Github account.
* Go to the Threefold Manual repository: [https://github.com/threefoldtech/info_grid](https://github.com/threefoldtech/info_grid)
* Fork the Development branch
* On the top right corner, click `Fork -> Create a new fork`
* Make changes in the forked repository
* To add a new section
* Add a new Markdown file to the [src](https://github.com/threefoldtech/info_grid/blob/development/src) directory
* Add the path of the Markdown file to [SUMMARY](https://github.com/threefoldtech/info_grid/blob/development/src/SUMMARY.md).
* To modify an existing section:
* Make the changes directly in the Markdown file
* Ask for a pull request
* In the forked repository, click `Contribute -> Open pull request`
* Once the pull request is accepted, the changes of the Development branch will be available here: [https://www2.manual.grid.tf](https://www2.manual.grid.tf)
* The Threefold team will regularly update the [Development branch](https://github.com/threefoldtech/info_grid) to the [Master branch](https://github.com/threefoldtech/info_grid/tree/master)
* The new content will thus be available here: [https://www.manual.grid.tf](https://www.manual.grid.tf)
Note: You can update your forked repository by clicking `Sync fork -> Update branch`.
***
### How to View the mdbook Locally
***
Once you've forked the TF Manual repository to your Github account, you might want to see the changes you've made before asking for a pull request. This will ensure that the final output is exactly what you have in mind.
To do so, you simply need to clone the forked repository on your local computer and serve the mdbook on a given port.
The steps are the following:
* In the terminal, write the following line to clone the forked `info_grid` repository:
* ```
git clone https://github.com/YOUR_GIT_ACCOUNT/info_grid
```
* make sure to write your own Github account in the URL
* To deploy the mdbook locally, first go to the **info_grid** directory:
* ```
cd info_grid
```
* Then write the following line. It will open the manual automatically.
* ```
mdbook serve -o
```
* Note that, by default, the URL is the following, using port `3000`, `http://localhost:3000/`
* You should now be able to see your changes.
***
### How to Install git and mdbook
***
To install git, follow the steps provided [here](https://github.com/git-guides/install-git).
To install mdbook, you can download the executable binaries available on the [GitHub Releases Page](https://github.com/rust-lang/mdBook/releases). Simply download the binary for your platform (Windows, macOS, or Linux) and extract the archive. The archive contains an mdbook executable which you can run to build your books. To make it easier to run, you can put the path to the binary into your PATH.
For more information, read the [mdbook Documentation](https://rust-lang.github.io/mdBook/guide/installation.html).
***
### Markdown File Template (Optional)
***
Here are some suggestions on how to organize a Markdown file (`.md`) when you submit contents to the ThreeFold Manual. This is not necessary, but it will ease the whole process.
* Title: Heading 1 (`#` in Markdown syntax)
* Main sections: Heading 2 (`##` in Markdown syntax)
* For Markdown files that contain a *Table of Contents*:
* Use `<h1>` instead of `#` for the _Title_ , and `<h2>` instead of `##` for the _Table of Contents_.
* This quickens editing when creating and updating the ToC ([read this for more details](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one#table-of-contents)).
* Other heading labels should use standard Markdown headings (`##`, etc.).
* If your text reaches heading level 4, you might want to separate your file into two or more files.
* A long article can be spread in many subsections.
***
## Questions and Feedback
If you have any questions or if you would like to share some feedback, let us know in this [Threefold forum post](https://forum.threefold.io/t/new-grid-manual/3783).

36
tosort/contribute/development_cycle.md Normal file
View File

@@ -0,0 +1,36 @@
The development cycle is explained below:
![Untitled presentation (1)](https://user-images.githubusercontent.com/8425762/170034170-7247a737-9d99-481d-9289-88d361275043.png)
Devnet:
- continuous development for active version
- can be reset
- should be against a branch named with the version being developed (example: 10.2.3)
Nextnet:
- for parallel version development
- oftentimes, the next major version while development has bugfixes
- should be against a branch named with the version being developed (example: 10.3.1)
QAnet:
- once development is complete, each component is tagged with an rc (example: 10.2.3-rc1) and the new version to be tested is deployed on QAnet
- this net is for INTERNAL QA
- Here, we expect most bugs to be reported
- Once QA signs off, it moves to testnet
Testnet:
- tag as beta release (example: 10.2.3-rc3-beta)
- This is for the community and stability testing
- should be almost completely stable
Mainnet:
- if testnet has no blockers for 2 weeks, community votes to move to mainnet
- everything is merged to main
- final release is tagged (example: 10.2.3)
## GOAL:
moving away from that model to be able to use ephermal environments instead of maintaining such environments, but now they're available for simplicity

422
tosort/contribute/development_process.md Normal file
View File

@@ -0,0 +1,422 @@
<h1> Development Process </h1>
Our project development process is characterized by agility, collaboration, and, most importantly, respect. We firmly believe in harnessing the collective ingenuity of our team, recognizing that each individual contributes invaluable insights to our codebase, our development process is completely managed on Github, using Github based projects.
<h2>Table of Contents</h2>
- [Quality Assurance (QA) Process](#quality-assurance-qa-process)
- [QA Responsibilities](#qa-responsibilities)
- [Daily Standups](#daily-standups)
- [Provide Test Plans](#provide-test-plans)
- [Test Execution](#test-execution)
- [Test Documentation](#test-documentation)
- [Verification and Closure](#verification-and-closure)
- [Cross-Environment Testing](#cross-environment-testing)
- [Bug Assessment Meetings (BAM)](#bug-assessment-meetings-bam)
- [Additional Testing Types](#additional-testing-types)
- [Expectations for QA Leads](#expectations-for-qa-leads)
- [Test Planning](#test-planning)
- [Test Strategy](#test-strategy)
- [Review and Closure](#review-and-closure)
- [Communication](#communication)
- [QA Verification and Testing](#qa-verification-and-testing)
- [Testplan](#testplan)
- [Verification Process](#verification-process)
***
## Product Definition on Home
`Home` repo serves a special role in the organization, it's the starting point of all development.
- It links to all products & components
- Put only stories, identified with tag `type_story` in the home repo
To streamline our development workflow, we have adopted the GitHub-style projects framework, with all repositories linked to the ThreeFold Grid (tfgrid) product (e.g., version 3.6.0).
- Various views, such as StoryCards for a high-level overview, repository-specific views, and prioritized views, enhance project visibility.
- All repositories are managed within a centralized project, ensuring unified control and coordination.
- Milestones, aligned with semantic versioning, serve as a means to categorize and organize issues, providing versioning per component.
- Each product is clearly outlined in a dedicated project section within the "home" repository.
- The home page in the home repository serves as a hub linking to individual product pages.
- Products are associated with relevant components slated for the upcoming release.
- Product release milestones are clearly marked on the product page.
- Release notes, accessible through each product, offer a historical overview with links to specific components used in each release.
- Interlinked relationships between products and components, as well as links to third-party products with specified version numbers, provide comprehensive tracking.
- Components are meticulously monitored within the same product project.
- A commitment to [semantic versioning](https://semver.org) is mandated for all components.
## Github Project
When creating a new project, please use the grid template project (private repository) available at `https://github.com/orgs/threefoldtech/projects/205`.
### Github project columns
- `No Status`
- Stakeholder or project owner suggests a feature/story/bug to be resolved in this release
- `Accepted`
- The project owner accepts the item, the issue will be worked on and he commits to solve within the release
- Once accepted = then escalation is needed if it can not be done in time
- `In progress`
- The issue is being worked on
- `Blocked`
- We are using the Kanban way of thinking - something in this swimlane needs to be resolved asap, can be e.g. a question
- Means issue cannot be completed, attention from e.g. stakeholders is needed
- `Verification` : work is being verified
- The team delivered the feature/bug/story
- Stakeholders need to agree that the issue has been resolved appropriately
- Project owner can never go from 'Verification' to 'Done' without approval from stakeholders (often represented by QA team)
- `Done`
- Everyone agreed (project owner and stakeholders) agreed that the issue was done ok
##### Project Special Columns
Some projects require special columns like the following
- `Pending Review`: Work is done, waiting for review; no need for daily progress updates.
- `Pending Deployment`: If deployment is needed for QA testing on the staging instance.
### Repository
Creating a repository involves establishing a foundation for collaborative development. Follow these guidelines to ensure consistency and best practices in repository creation.
#### Naming
- Choose a clear and descriptive name for the repository.
- Use lowercase letters and hyphens for improved readability.
#### README
- Include a comprehensive README.md file.
- Provide essential information about the project, including setup instructions, dependencies, and usage guidelines.
#### License
- Include a LICENSE file specifying the project's licensing terms, threefoldtech is using [Apache2 License](https://github.com/threefoldtech/info_grid/blob/master/LICENSE).
#### Github Templates
- Use github templates to provide proper template for issues [bug_report](./bug_report.md) or [feature request](./feature_request.md)
- Use github templates to provide proper template for [pull requests](./PULL_REQUEST_TEMPLATE.md)
#### Expected Workflows
- Set up a continuous integration (CI) pipeline using a tool like GitHub Actions.
- Include linting, tests and code quality checks in the CI process.
- Set up automation to deployment on staging, and production server
- Building docker images
- Building flists
- Pushing to the hub
- Publishing packages
### Issues
Consider the following for Effective Issue Reporting
1. **Title:**
- Provide a clear and concise title that summarizes the issue.
2. **Description:**
- Offer a detailed description of the issue, including what you expected to happen and what actually occurred.
- Provide steps to reproduce the issue, if possible.
- Include any error messages received.
3. **Environment:**
- Specify the environment in which the issue occurred (e.g., operating system, browser, version).
4. **Attachments:**
- Attach relevant files or screenshots to help visualize the problem.
5. **Issue Type:**
- Label the issue with an appropriate type (e.g., bug, feature request, question).
6. **Priority:**
- If applicable, assign a priority level to indicate the urgency of the issue.
7. **Version Information:**
- Include information about the version of the software or application where the issue was encountered.
8. **Labels:**
- Apply relevant labels to categorize the issue (e.g., priority levels, type of issue).
9. **Reproducibility:**
- Clearly state whether the issue is reproducible and under what conditions.
10. **Additional Context:**
- Provide any additional context that might help in understanding and addressing the issue.
11. **Assigned:**
- If known, assign the issue to the responsible team member or developer.
12. **Discussion:**
- Engage in discussions with the development team and other stakeholders to gather insights and potential solutions.
By following these guidelines, you contribute to a more efficient issue resolution process, enabling developers and the team to address concerns promptly and effectively.
#### Issue Labels
See [issue labels](issue_labels.md)
#### Branch Names in Issue titles
Each issue has the name of a branch in the title as [development_something], the name 'development' can be skipped and its the default or previous could also be written as [something] but don't forget branch is development_...
If not specified, it is to be fixed/developed on development.
#### Milestones for Issues
We use milestones for version numbers e.g `1.4.2` means this issue is going to be part of the release of `1.4.2` of the component.
> It's very important that nobody works on any issue in milestones not part of the global project plan
- No milestone means need to be sorted
- Number e.g `1.4.2` means
So issues with no milestones can only be in 1 condition: new and not sorted out yet where (repo) it belongs
### Branching
We encourage collaborative branching. Meaning any group of people working within the same scope are highly encouraged to work on the same branch, trusting and communicating with one another.
Our branching strategy is:
- `master` is the last stable release
- `master_$hotfix` is only for solving BLOCKING issues which are in the field on the last release
- short living
- `development` is where all stories branch from, and the one that has hotfixes if needed
- `development_$storyname`
- branch for a story
- always updated from development(_hotfixes)
- `development_$storyname_$reviewname`
- short living branch for when reviews are needed for a story
- `development_hotfixes` short living hotfix(es) to allow people to review and then put on development
- now everyone should update from or development or development_hotfixes
- development_hotfixes is always newer than development
- `integration` is a branch used to integrate development branches
- never develop on it, its for verifying & doing tests
We have branches for new features/disruptive changes. These have a prefix of `development_<relevantname>`
Each project and story should define which branches to use & the branching strategy.
There should never be any branch on the system which can not be found back by looking at the stories in the `home` repo.
Title of the story : in between []
### Pull Requests
When developers or a group initiate work on a separate branch and seek input from their peers, it is recommended to promptly open a `draft pull request` for seamless communication. Upon completion of the work, opening a pull request signals that the work is:
- Complete as Defined in the Project: The work aligns with the predefined goals and specifications outlined in the project.
- Well Tested: Thorough testing has been conducted to ensure the reliability and functionality of the code.
- Well Documented: Comprehensive documentation accompanies the code, aiding in understanding and future maintenance.
#### Pull Requests Best Practices
When creating pull requests (PRs), adhere to the following best practices for effective collaboration:
- Early Draft PRs: Open a draft pull request as soon as work begins on a different branch. This allows for ongoing communication and collaboration with peers throughout the development process.
- Timely Updates: Regularly update the PR as new changes are made to keep reviewers informed of progress.
- Clear and Concise Title: Use a clear and concise title that summarizes the purpose or goal of the pull request.
- Detailed Description: Provide a comprehensive description of the changes made, the problem solved, and any relevant context. This aids reviewers in understanding the purpose and impact of the changes.
- Link to Issues: If the pull request addresses specific issues, link them to provide additional context and traceability.
- Reviewers and Assignees: Assign the appropriate reviewers and, if applicable, assignees to ensure that the right people are involved in the review process.
- Complete Work: Ensure that the work is complete as defined in the project requirements. Address any outstanding issues before marking the PR as ready for review.
- Thorough Testing: Verify that the code has undergone thorough testing. Include details about the testing strategy and results in the PR description.
- Documentation: Confirm that the changes are well-documented. Documentation should not only explain how the code works but also guide future developers on its usage and maintenance.
- Address Feedback: Be responsive to feedback from reviewers. Address comments and concerns promptly to facilitate a smooth review process.
- Code Style and Standards: Ensure that the code follows established style guidelines and coding standards. Consistent formatting contributes to maintainability.
- Status Checks: Ensure that automated status checks, such as continuous integration (CI) tests, pass successfully before merging.
By adhering to these best practices, you contribute to a collaborative and efficient development process, fostering a culture of high-quality code and effective communication within the team.
### Commits
Clear and informative commit messages are essential for understanding the history of a project. Follow these guidelines to create meaningful commit messages.
## Message Structure
### Header
- Start with a concise one-line summary
- Use present-tense verbs (e.g., "Add," "Fix," "Update") to describe the action.
### Body
- Optionally, provide a more detailed explanation.
- Break long explanations into bullet points if needed.
## Be Descriptive
- Clearly describe the purpose of the commit.
- Include information about why the change is necessary.
## Reference Issues
- If the commit is related to an issue, reference it in the message.
- Use keywords like "Fixes," "Closes," or "Resolves."
## Consistency
- Be consistent with your writing style and formatting.
- Use the imperative mood consistently throughout.
## Examples
### Good Example
Here's a good example of a commit message
```
Add user authentication feature
- Implement user login functionality
- Enhance user registration form
- Fixes #123
```
### Bad Example
```
Changes
- Bug fix
- Update
- Important changes
```
### Merge or Rebase
If you're the sole developer on the branch, you can use rebase, if more people are collaborating together, use merge
### Merge or Squash merge
Squash only when it makes the history cleaner. Feature branch is a good example, because it is often short-lived, small, and authored by 1 developer.
On the other hand, use regular merge for big feature co-authored by multiple developers eg. long-lived branches, please be aware of the [Disadvantages of squash merges](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits)
### Releasing Process
Before tagging a release, open a branch named with the intended version e.g 10.5.x with the quality level
- alpha: doesn't have all the features, but you can use the features in there
- beta: no major, or blocking bugs. All features working for the customer as promised, no blocking bugs
- production: no major, no blocking, no minor bugs and the documentation is ready
check the [release process document](release_process.md) for more information
#### Blocking
Issues categorized as blockers include:
- Inability of the customer to access the functionality as described in the manual.
- Stability concerns that impede progress, particularly instances where the system crashes.
- Security issues that act as barriers to further development.
- Stability issues that hinder smooth operation.
- Performance concerns labeled as blockers when they prevent continuation.
- Performance issues classified as major when they allow for continued work.
#### Progress Reporting
In teams operating remotely, complete transparency is of utmost importance.
Visibility into development progress is crucial and is best achieved through the use of storycards and issues.
To facilitate clear communication, commenting daily is a critical aspect of our process. We advocate for the following format, which aids in asynchronous communication:
```
## Work Completed:
Summarize the tasks successfully finished in relation to the issue. Provide specific details to ensure clarity.
## Work in Progress (WIP):
Detail ongoing efforts and remaining tasks related to this issue. Clearly outline items currently being worked on and those still needing attention.
## Investigation and Solution:
If no work has been completed or is in progress, elaborate on the investigative work undertaken to address the issue. Provide insights into the problem, and if a solution was reached, include it.
```
For issues or stories labeled with `priority_critical`, continuous updates should be at least two updates per day to keep stakeholders informed.
Including an Estimated Time of Arrival (ETA) in the comments is essential. While it serves as an estimation subject to change with new findings, it provides a valuable projection of completion.
# Quality Assurance (QA) Process
QA plays a crucial role in delivering high-quality software. This document outlines responsibilities, expectations, and best practices.
## QA Responsibilities
### Daily Standups
- Attend daily standups for progress updates, issue discussions, and coordination.
### Provide Test Plans
- Collaborate on test plans for each sprint.
### Test Execution
- Execute test plans manually and through automated testing.
- Log and prioritize defects.
- Track nightly tests.
### Test Documentation
- Maintain updated test documentation.
### Verification and Closure
- Verify issues and user stories before closure.
### Cross-Environment Testing
- Conduct test runs across different environments.
### Bug Assessment Meetings (BAM)
- Conduct BAM sessions twice weekly to address community feedback, covering both `test_feedback` repository and active projects.
### Additional Testing Types
- Expand responsibilities to include various testing types such as:
- Performance testing
- Security testing
- Compatibility testing
- Usability testing
- Regression testing
## Expectations for QA Leads
### Test Planning
- Lead the creation of detailed test plans.
### Test Strategy
- Define a testing strategy, emphasizing automation.
### Review and Closure
- Review and close issues, ensuring alignment with the test plan.
### Communication
- Facilitate communication between QA and development teams.
## QA Verification and Testing
### Testplan
- Provide a comprehensive test plan, authored exclusively by the QA lead that serves as the source of truth for the verification process
### Verification Process
- Verify stories in a two-step process
- As soon as the story is moved to In Verification column, QA team can pickup the issue, they need to log their scenarios, executions and link to the testcase in the testplan.
- QA lead can then verify it's aligned to the original requirements and it was properly verified before closing
- QA leads need to test the main features by themselves.
- Automate regression testing through github workflows, and any other means needed.

16
tosort/contribute/feature_request.md Normal file
View File

@@ -0,0 +1,16 @@
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---
## Is your feature request related to a problem? Please describe
A clear and concise description of what the problem is. Ex. I'm always frustrated when \[...]
## Describe the solution you'd like
A clear and concise description of what you want to happen.

24
tosort/contribute/issue_labels.md Normal file
View File

@@ -0,0 +1,24 @@
# Issue Labels Usage Guidelines
Kindly refrain from using labels other than the specified ones.
## Priority-based Labels
- `priority_critical`: This label indicates that the issue requires immediate attention, with a maximum resolution timeframe of the same day.
- If the assigned developer deems this timeline unachievable, they must escalate the issue immediately.
- The term "critical" implies that the resolution is of utmost urgency, and everyone involved should prioritize it until it is resolved.
- `priority_major`: This label designates issues that are very urgent and should be addressed within a minimal timeframe, typically within 1-2 days but no more than 3 days.
- If the developer anticipates challenges in meeting this timeframe, they are required to escalate the issue promptly.
- `priority_minor`: Issues labeled as such are given a lower priority and are typically positioned towards the end of the sprint cycle.
## Types Labels
- `type_bug`
- `type_feature`
- `type_question`
- `type_story`: This label is used to distinguish story cards, providing an overview of a use case the team aims to achieve.
### For monorepos
Repository owners are free to create labels per component in the monorepo for easier repo management

53
tosort/contribute/release_process.md Normal file
View File

@@ -0,0 +1,53 @@
<h1> Release Process </h1>
<h2>Table of Contents</h2>
- [Github projects](#github-projects)
- [Releasing the Grid](#releasing-the-grid)
- [Environments](#environments)
- [Versions](#versions)
- [Branching/Tagging](#branchingtagging)
- [Blocking Bugfixes for Mainnet](#blocking-bugfixes-for-mainnet)
***
## Github projects
- We are going to use new github style projects to manage the development process, all repos are linked against tfgrid product e.g 3.6.0
- You can have different views e.g StoryCards only view for Highlever overview, a view by repositories, priorities
- We will drive all repos from that one project
- We should use milestones (semantic version to sort out the issues)
## Releasing the Grid
### Environments
- Grid releases are no longer linked to an environment in a pipeline, while this makes sense in lots of scenarios, it won't scale
- An environment hosts a specific grid version based on the components it has
- In the future, we should be able to create ephermal environments e.g deploy this grid version on these X number of nodes
### Versions
- Releasing should follow [semantic versioning](https://semver.org/)
- Every grid release is linked to X number of components. For example, TFGrid 3.6.1 is linked to terraform 1.0.0, portal 2.0.1, .. etc
### Branching/Tagging
- As mentioned above, releases should should follow semantic versioning. The tag itself is prefixed with a `v`. so vx.y.z or vx.y.z-rc1
- Devnet(s) should host development branches and once it reaches a specific quality they get verified on that branch
- THIS IS NOT TRUE: it can be that on a dev net you have production components
- Once verification happens and everything goes ok, we should tag a release of a component
- Once all components are ready a grid release is complete and we can host that release on whatever environment
- Container image tags must not contain the `v`-prefix
### Blocking Bugfixes for Mainnet
- In case of a blocking bug happening only on mainnet, we branch out of the tag on the affected component repository
- do the fix on that branch
- host a new grid release on a testing environment to verify
- tag the new component
- merge to trunk
- create a new grid release
- host that grid release (its components) on mainnet