diff --git a/docs/index.md b/docs/index.md index d887c50..96857d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,11 +25,11 @@ Which is when we realized, there was no single chain agnostic token we can use t **$FULA** will be the catalyst for keeping the infrastructure online at all times and getting users to store their photos and video, for as long as they want. Storage providing and compute providers are two sides of the same coin. Providers require payment for offering their service to the public. And consumers need a corresponding way to pay for said services. -### Enter [BAS](./welcome/bas) +### Enter [BAS](./introduction/bas) We created the first uniform **Blockchain Attached Storage (BAS)** device! As a provider, you can use your storage device(s) to completely own your data and gain rewards for offering up your extra storage to the public. And as a consumer, can pay-as-you-go! It'll be like you have access to infinite storage and just pay for what you need to keep your data alive for as long as you like. -### Enter [FxBlox](./welcome/blox) +### Enter [FxBlox](./introduction/blox) FxBlox, or Blox, is the brand-new hardware that is empowering it all. Beautiful design, power-efficient board, and next-gen processing is not gate-kept by inflated pricing. Bloxes are competitively priced and offer the **lowest** barrier to entry in any decentralized storage blockchain. Our network has the potential to vertically and horizontally scale faster than any protocol before. @@ -37,6 +37,6 @@ FxBlox, or Blox, is the brand-new hardware that is empowering it all. Beautiful To enable any developer to build apps and services on this brand new protocol, we introduce the **Fula API**. An open, interoperable specifications that enables developers to write permissionless, decentralized apps for consumers and to get paid for their work. -## [Fula Network](./welcome/fula) +## [Fula Network](./introduction/fula) All together we get the **Fula Network**. This network has power in numbers, it is for the people, and will create a new internet that fixes the security and other fundamental problems with the internet of today. \ No newline at end of file diff --git a/docs/welcome/bas.md b/docs/introduction/bas.md similarity index 100% rename from docs/welcome/bas.md rename to docs/introduction/bas.md diff --git a/docs/welcome/blox.md b/docs/introduction/blox.md similarity index 100% rename from docs/welcome/blox.md rename to docs/introduction/blox.md diff --git a/docs/introduction/contribute/contribute.md b/docs/introduction/contribute/contribute.md new file mode 100644 index 0000000..e591b10 --- /dev/null +++ b/docs/introduction/contribute/contribute.md @@ -0,0 +1,44 @@ +--- +title: How to Contribute +id: contribute +--- + +Thank you for your interest in contributing to our open source repositories on GitHub! Your contributions help us improve the services and make everyone's experience even better. Here's how you can get involved: + +## Hold [Discussions](./contribute/contribution-tutorial#discussing-the-issue) + +The [Discussion tab](https://github.com/orgs/functionland/discussions) on the Functionland GitHub page can be used for general questions, feedback, raising bugs/feature requests, or discussions related to our projects. Feel free to engage with other community members and share your ideas or suggestions. + +![discussions tab on github](/img/welcome/discussions.png) + +## Submit an [issue](./contribute/contribution-tutorial/#finding-an-issue) + +If you encounter a bug, have a feature request, or come across an explicit error, please submit an issue to the appropriate repository. Follow these guidelines for formatting the subject line: +- For bugs: `[BUG] - subject line` +- For feature requests: `[Feature Request] - subject line` +- For explicit errors: `[Error] - error message` + +Make sure to include which device you have (Lite or Lite Plus), app version number, what happened leading up to the issue, and the symptom you are experiencing. You can find logs under `Settings` -> `Blox logs`, please submit `Go-Fula` and `Node` logs if you can or applicable. + +You can also follow the templates in Github to know what information to include in your post. + +## Submit a [pull request (PR)](./contribute/contribution-tutorial#create-a-pull-request) + +We welcome contributions from the community! If you'd like to fix a bug, add a feature, or improve documentation, please submit a pull request. Make sure to follow our contribution guidelines and include a clear description of the changes you've made. + +You can also follow the templates in Github to know what information to include in your post. + +## Choose the right repository + +When deciding where to submit your issue or PR, consider where you encountered the problem or want to make a change: +- **For issues within the FxBlox app or FxFiles**: Submit to the [fx-components repository](https://github.com/functionland/fx-components). +- **For issues with the firmware**: Submit to the [fula-ota repository](https://github.com/functionland/fula-ota). +- **For issues related to the FxFotos app**: Submit to the [fx-fotos repository](https://github.com/functionland/fx-fotos). + +Please ensure that you submit your contribution to the appropriate repository based on where you experienced the issue or want to make a change. If you are unsure which repository to raise the concern in, start a Discussion thread so we can narrow down the problem! + +## Contribute to [Fula docs](https://github.com/functionland/docs) + +Technical writers of any level are greatly appreciated. If you are considering contributing to the documentation, please take a look at our [Styling](./contribute/styling) and [Writing](./contribute/writing) guides to learn more about our writing styles. + +Thank you for contributing to our projects and helping us build better software together! diff --git a/docs/introduction/contribute/contribution-tutorial.md b/docs/introduction/contribute/contribution-tutorial.md new file mode 100644 index 0000000..29201d0 --- /dev/null +++ b/docs/introduction/contribute/contribution-tutorial.md @@ -0,0 +1,105 @@ +--- +title: Contribution Tutorial +id: contribution-tutorial +--- +This style guide is adapted from IPFS's ["__Contribution Tutorial__"](https://docs.ipfs.tech/community/contribute/contribution-tutorial/) article. + +While the [grammar, formatting, and style](./styling-guide.md) and the [writing guide](./writing-guide.md) can both help you write good content for the Fula docs, they don't delve into _how_ you can submit your content changes. This guide will walk you through finding an issue, fixing it, and then submitting your fix to `functionland/docs`. + +There are plenty of small-sized issues around IPFS documentation that make for easy, helpful contributions to the Fula net project. Here, we'll walk through: + +1. Finding an issue. +2. Discussing the issue. +3. Creating a fix. +4. Submitting a _pull request_. +5. Waiting for a review. +6. Merging your fix. + +This may look like a lot of steps for a small issue fix, but they're all necessary to make sure we keep the docs in this project up to standard. Plus, you're not on your own — half these steps can be completed by Fula staff! + +## Finding an issue + +The Fula net project is hosted in GitHub. There's a bunch of reasons for this, one of them being that GitHub comes with an issue tracker, which enables the core Fula team to field problems from the community. All community issues can read the docs, find issues, and raise issues in the docs repository (called a _repo_ for short). + +All issues involving the Fula docs themselves can be found in the [`functionland/docs` repo](https://github.com/functionland/docs) under the [**Issues** tab](https://github.com/functionland/docs/issues/). Here you can see all the issues that are currently open. We try to tag each issue with relevant descriptive tags. Tags like _difficulty_ and _size_ can give a sense of the amount of effort a task will take to complete. + +Let's jump into finding an issue. + +1. Go to the Functionland repository at [github.com/functionland/docs](https://github.com/functionland/docs). +2. Select the **Issues** tab. +3. Click the **Label** dropdown and select the **help wanted** tag. +4. Select an issue that interests you. + +Make a note of the issue number and keep it handy for later. + +## Discussing the issue + +As you can probably tell from the available tags, there are lots of different types of issues. Some are tiny one-sentence changes, and others are sizable projects that require a rewrite of several pages. For small issues, there may be very little or no discussion. There's no need to waste everybody's time talking about changing a broken link. But more significant issues will likely need input from different members of the project. + +When adding to a discussion, remember that it may take days or weeks to conclude an issue. With this in mind, try to include all the relevant information anyone might need within each message. + +Let's add to the discussion of the issue you've chosen: + +1. Read through all the previous posts to get up to speed on the issue. +2. Add any comments you feel are necessary. +3. If you still want to tackle this issue, post a message saying that you'd like to take ownership of it. + +Once you've claimed ownership of an issue, a member of the core Fula team will assign you to it. If this is a large issue, someone from the Fula team will check in with you from time to time and make sure you've got everything you need to progress with the issue. + +## Creating a fix + +If you've got this far, then you should have an issue in hand and a basic idea of how to fix it. Next up is implementing your fix! The process goes something like this: + +1. Create a _fork_. +2. Make changes locally on your machine. +3. Push your changes. + +If you're not familiar with Git and GitHub, then the phrase _fork_ might not mean much to you. Essentially, a _fork_ of a project is your own personal copy of that project. You can make as many changes to this copy whenever you want because you own it. The idea is that you can modify this personal copy and send your changes to the project team, who can then review all the work you've done. + +The process for creating a fork of an existing piece of Fula documentation is incredibly simple: + +1. Go to the `functionland/docs` repository in [GitHub](https://github.com/functionland/docs). +2. Select **Fork** to create a copy of the project. +3. Clone your copy of the project down to your local machine: + + ```bash + git clone https://github.com/YOUR_USERNAME/docs.git + ``` + +4. Make your changes locally. +5. Once all your changes are complete, make sure to push everything back to GitHub: + + ```bash + git add . + git commit -m "Fixed a broken URL, issue #123." + git push + ``` + +When adding a commit comment that actively fixes an issue within the project, try to summarize the fix in a few words and quote the issue number. Following this convention makes it easier for other people to quickly see what you've done. + +## Create a pull request + +Once you're done making commits and are ready to get a core team member's review of your work, it's time to create a pull request. + +1. Go to the `functionland/docs` repository on [GitHub](https://github.com/functionland/docs). +2. Select the **Pull requests** tab. +3. Click **New pull request**. +4. Click **compare across forks** and select your repository from the **head repository** dropdown. +5. Leave a comment to expand upon your changes. +6. Click **Create pull request**. + +GitHub will check if your changes create any merge conflicts with the branch you are trying to merge into. + +## Waiting for a review + +Before your changes can be merged into the project, they have to pass a review. `functionland/docs` has automatic tests that run against a pull request. These tests must pass _before_ the changes can be merged into the project. If they fail, you will see a red x on the last commit. If you have email preferences turned on, you would also receive an email of the result. + +Depending on the size of the pull request, this could take anywhere from a few minutes to a few days to review everything. Depending on the complexity of the pull request, there may be further discussion regarding your changes. Keep returning to GitHub and checking your [notifications page](https://github.com/notifications) to make sure you don't miss anything. + +## Merge your fix + +Once your pull request has been approved, it's ready to be merged into the project! Only project members with the correct rights can merge changes into the project, but you'll be notified as soon as the merge is complete. + +## Finishing up + +So there you have it! You've successfully completed your first contribution to the Fula documentation. We're always on the lookout for great writers and educators to help us improve the Fula docs and make the internet better for everyone, so keep up the good work! diff --git a/docs/introduction/contribute/styling-guide.md b/docs/introduction/contribute/styling-guide.md new file mode 100644 index 0000000..731e824 --- /dev/null +++ b/docs/introduction/contribute/styling-guide.md @@ -0,0 +1,297 @@ +--- +title: Style Guide +id: styling +--- +This style guide is adapted from IPFS's ["__Grammer, formatting, and style__"](https://docs.ipfs.tech/community/contribute/grammar-formatting-and-style/) rules. + +This page details the syntax and formatting rules for writing Fula documentation. For more conceptual ideas of writing, check out the [writing guide](writing-guide.md). + +## Grammar and spelling + +Here are some language-specific rules that the Fula documentation follows. If you use a writing service like [Grammarly](https://www.grammarly.com/), most of these rules are turned on by default. + +### American English + +While Fula is a global project, the fact is that American English is the most commonly used _style_ of English used today. With that in mind, when writing content for the Fula project, use American English spelling. The basic rules for converting other styles of English into American English are: + +1. Swap the `s` for a `z` in words like _categorize_ and _pluralize_. +2. Remove the `u` from words like _color_ and _honor_. +3. Swap `tre` for `ter` in words like _center_. + +### The Oxford comma + +Follow each list of three or more items with a comma `,`: + +| Use | Don't use | +| ----------------------------- | ---------------------------- | +| One, two, three, and four. | One, two, three and four. | +| Henry, Elizabeth, and George. | Henry, Elizabeth and George. | + +### Acronyms + +If you have to use an acronym, spell the full phrase first and include the acronym in parentheses `()` the first time it is used in each document. + +> Example: Virtual Machine (VM), Decentralized Web (DWeb). + +### Differentiation between token and network + +Capitalization is required when referring to the $FULA token, but not required when referring to the Fula network. + +Example: +> +> $FULA is going to the moon! +> +> I uploaded my files to the Fula net to save my files to the decentralized cloud. + +## Formatting + +How the Markdown syntax looks, and code formatting rules to follow. + +### Syntax + +The Fula Docs project follows the _GitHub Flavored Markdown_ syntax for markdown. This way, all articles display properly within GitHub itself. This gives readers the option to view articles on [the docs website](https://docs.fx.land) or [its GitHub repo](https://github.com/functionland/docs). + +#### Relative links + +Relative links in Docusaurus can be created using a pages' `ID` tag, or their file name. If you include internal (relative) links to other content on the Fula docs site, please link to them using full relative paths (e.g. use `../` for climbing a directory) and specifying the file's full name (e.g. `awesome-tutorial.md#subheading`). This ensures that users who read docs content directly in-repo on GitHub's web UI are able to follow relative links correctly. + +### Rules + +We use the rules set out in the [VSCode Markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension. You can import these rules into any text editor like Vim or Sublime. All rules are listed [within the Markdownlint repository](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md). + +We highly recommend installing [VSCode](https://code.visualstudio.com/) with the [Markdownlint](https://github.com/DavidAnson/vscode-markdownlint) extension to help with your writing. The extension shows warnings within your markdown whenever your copy doesn't conform to a rule. + +## Style + +The following rules explain how we organize and structure our writing. The rules outlined here are in addition to the [rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md) found within the [Markdownlinter extension](https://github.com/DavidAnson/vscode-markdownlint). + +### Text + +The following rules apply to editing and styling text. + +#### Titles + +1. All titles follow sentence structure. Only _names_ and _places_ are capitalized, along with the first letter of the title. All other letters are lowercase: + + ```markdown + ## This is a title + + ### Only capitalize names and places + + #### The capital city of France is Paris + ``` + +2. Every article starts with a _front-matter_ `title` and `id`: + + ```markdown + --- + title: Example article + id: arbitrary-id + --- + + ## This is a subtitle + + Example body text. + ``` + + In the above example, `title:` serves as a `