From 8a1a454e7e65cb3a0efaeec9aab6a03dc6d92352 Mon Sep 17 00:00:00 2001 From: jmc Date: Mon, 11 Sep 2023 14:42:17 +0100 Subject: [PATCH 1/2] add intro and contributing pages --- docs/src/SUMMARY.md | 1 + docs/src/contributing.md | 57 ++++++++++++++++++++++++++++++++++++ docs/src/index.md | 63 ++++++++++++++++++++++++++++++++++++++-- 3 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 docs/src/contributing.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 898706e066..88caf78b63 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -78,5 +78,6 @@ * [Sequence types in memory](spec/data_layout/memory/sequence_types_in_memory.md) * [Function calls](spec/function_calls.md) +* [Contributing](contributing.md) * [Release Notes](release_notes.md) * [Code of Conduct](code_of_conduct.md) diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 0000000000..8493fba11e --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1,57 @@ +# Contributing + +You *can* contribute to Fe! + + +## Ways to contribute: + +### 1. Reporting or fixing issues. + +If you find problems with Fe you can report them to the development team on the project [Github](https://github.com/ethereum/fe). +You are also welcome to work on existing issues, especially any tagged `good first issue` on the project issue board. + +### 2. Improving the docs. + +We always appreciate improvements to the project documentation. This could be fixing any bugs you find, adding some detail to a description or explanation or developing a new user guide. + +To add to the docs you can fork the Fe Github repository and make updates in the `/docs` directory. You can build and serve locally using `mdbook build && mdbook serve`. Then, when you are happy with your changes you can raise a pull request to the main repository. + +### 3. Developing Fe + +You are also welcome to work on Fe itself. There are many opportunities to help build the language, for example working on the compiler or the language specification, adding tests or developing tooling. + +It is a good idea to connect with the existign Fe community to find out what are the priority areas that need attention and to discuss your idea in context before putting time into it. You can find Fe developers on the [Discord](https://discord.gg/yCT6NYBb) or you can use the [Github issue board](https://github.com/ethereum/fe/issues). + +### 4. Community engagement + +We appreciate help answering questions on the Discord and other platforms such as Stack Exchange or Twitter. + +> Please note that this project has a [Code of Conduct](code_of_conduct.md). By participating in this project — in the issues, pull requests, or Discord channel — you agree to abide by its terms. + +## Processes + +### Reporting issues + +To report an issue, please use the [Github issue board](https://github.com/ethereum/fe/issues). When reporting issues, please mention the following details: + +- Fe version. +- your operating system. +- the steps required to reproduce the issue +- actual vs expected behaviour +- any error messages or relevant logs +- the specific source code where the issue originates + +The appropriate place for technical discussions about the language itself is the Fe [Discord](https://discord.gg/yCT6NYBb). + +### Rasing Pull Requests + +Please [fork the Fe repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and raise [pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) against the `master` branch. + +Your commit messages should be concise and explain the changes made. Your pull request description should explain why the changes were made and list the specific changes. If you have to pull in changes from `master` to your fork (e.g. to resolve merge conflicts), please use `git rebase` rather than `git merge`. + +New features should be accompanied by appropriate tests. + +Finally, please make sure you respect the coding style for this project. + + +Thank you for contributing to Fe! \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 6a3e72e62e..49f0315140 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,3 +1,62 @@ -# The Fe Guide -Fe logo \ No newline at end of file +

+
Fe logo
+ +## What is Fe? + +Fe is the *next generation smart contract language for Ethereum*. + +Fe is a [smart contract](https://ethereum.org/en/smart-contracts/#introduction-to-smart-contracts) language that strives to make developing Ethereum smart contract development *safer, simpler and more fun*. + +Smart contracts are programs executed by a computer embedded into Ethereum clients known as the [Ethereum Virtual Machine (EVM)](https://ethereum.org/en/developers/docs/evm/). The EVM executes bytecode instructions that are not human readable. Therefore, developers use higher-level languages that compiles to EVM bytecode. + +Fe is one of these languages. + +## Why Fe? + +Fe aims to make writing secure smart contract code a great experience. With Fe, writing safe code feels natural and fun. + +Fe shares similar syntax with the popular languages [Rust](https://doc.rust-lang.org/book/) and [Python](https://www.python.org/), easing the learning curve for new users. It also implements the best features from Rust to limit dynamic behaviour while also maximizing expressiveness, meaning you can write clean, readable code without sacrificing compile time guarantees. + +Fe is: +- statically typed +- expressive +- compiled using Yul +- built to a detailed language specification +- able to limit dynamic behaviour +- rapidly evolving! + + +## Who is Fe for? + +Fe is for *anyone that develops using the EVM*! + +Fe compiles to EVM bytecode that can be deployed directly onto Ethereum and EVM-equivalent blockchains. + +Fe's syntax will feel familiar to Rust and Python developers. + +Here's what a minimal contract looks like in Fe: + +```fe +contract GuestBook { + messages: Map> + + pub fn sign(mut self, ctx: Context, book_msg: String<100>) { + self.messages[ctx.msg_sender()] = book_msg + } +} +``` + + +## What problems does Fe solve? + +One of the pain points with smart contract languages is that there can be ambiguities in how the compiler translates the human readable code into EVM bytecode. This can lead to security flaws and unexpected behaviours. + +The details of the EVM can also cause the higher level languages to be less intuitive and harder to master than some other languages. These are some of the pain points Fe aims to solve. By striving to *maximize both human readability and bytecode predictability*, Fe will provide an enhanced developer experience for everyone working with the EVM. + + +## Get Started + +You can read much more information about Fe in these docs. If you want to get building, you can begin with our [Quickstart guide](quickstart/index.md). + +You can also get involved in the Fe community by contributing code or documentation to the project Github or joining the conversation on [Discord](https://discord.gg/yCT6NYBb). Learn more on our [Contributing](contributing.md) page. \ No newline at end of file From d36288428b694bbb058d29a7bb35a8197f418a07 Mon Sep 17 00:00:00 2001 From: jmc <33655003+jmcook1186@users.noreply.github.com> Date: Wed, 20 Sep 2023 13:41:12 +0100 Subject: [PATCH 2/2] add note on v2 branch Signed-off-by: jmc <33655003+jmcook1186@users.noreply.github.com> --- docs/src/contributing.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/src/contributing.md b/docs/src/contributing.md index 8493fba11e..0f531ef0f9 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -20,7 +20,11 @@ To add to the docs you can fork the Fe Github repository and make updates in the You are also welcome to work on Fe itself. There are many opportunities to help build the language, for example working on the compiler or the language specification, adding tests or developing tooling. -It is a good idea to connect with the existign Fe community to find out what are the priority areas that need attention and to discuss your idea in context before putting time into it. You can find Fe developers on the [Discord](https://discord.gg/yCT6NYBb) or you can use the [Github issue board](https://github.com/ethereum/fe/issues). +It is a good idea to connect with the existing Fe community to find out what are the priority areas that need attention and to discuss your idea in context before putting time into it. You can find Fe developers on the [Discord](https://discord.gg/yCT6NYBb) or you can use the [Github issue board](https://github.com/ethereum/fe/issues). + +> **Please note** that there has been a substantial amount of work done on the `fe-v2` branch of the repository that includes breaking changes. When merged `fe-v2` will revert new contributions based on `master`. +> +> To make your work v2 ready you can build off the `fe-v2` branch. It is recommended to seek out issues tagged `v2` in the Github Issue board. ### 4. Community engagement