Mirrors/astuto
1
0
Fork 0
mirror of https://github.com/astuto/astuto.git synced 2025-12-15 03:07:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update README and CONTRIBUTING (#124)

Browse Source
This commit is contained in:
Riccardo Graziosi
2022-06-13 15:04:57 +02:00
committed by GitHub
parent e2065b2c5e
commit 07ca2a304a
2 changed files with 73 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
CONTRIBUTING.md
View File

@@ -1,147 +1,69 @@
# Contributing Guidelines <!-- omit in toc -->
# Contributing guidelines
Thanks for taking the time to contribute! We would like the Astuto community to be a welcoming environment for both seasoned programmers and absolute beginners. The following guidelines should help you get started regardless of your skill level.
Thanks for taking the time to contribute 😁
- [How to contribute](#how-to-contribute)
- [Reporting bugs](#reporting-bugs)
- [Proposing features](#proposing-features)
- [Coding](#coding)
- [Getting involved in the community](#getting-involved-in-the-community)
- [Styleguides](#styleguides)
- [Git commit messages](#git-commit-messages)
- [Coding conventions](#coding-conventions)
- [General coding conventions](#general-coding-conventions)
- [Ruby coding conventions](#ruby-coding-conventions)
- [JavaScript coding conventions](#javascript-coding-conventions)
- [This is my first contribution! Help!!](#this-is-my-first-contribution-help)
- [Workflow](#workflow)
- [Look for label "good first issue"](#look-for-label-good-first-issue)
- [Any doubt?](#any-doubt)
- [Community](#community)
- [Code of Conduct](#code-of-conduct)
- [Language](#language)
- [Want to chat?](#want-to-chat)
- [Credits](#credits)
We would like the Astuto community to be a welcoming environment for both seasoned programmers and absolute beginners. The following guidelines should help you get started regardless of your skill level.
## How to contribute
There are various ways to contribute to Astuto. In this section we list the most common ones.
There are many ways to contribute to Astuto, not just coding. In this section we list the most common ones:
### Reporting bugs
- **Getting involved in the community**: we love to hear opinions about our product. Dropping a comment on an open issue or pull request or joining the discussion on the [Discord server](https://discord.com/invite/SrtUMRp) is an easy yet impactful way to contribute.
- **Reporting bugs or proposing features**: [open a new issue](https://github.com/riggraz/astuto/issues/new) on GitHub. Before posting, check if a similar issue has already been reported. Try to be concise but also unambiguous.
- **Translating Astuto into a new language**: we want Astuto to speak all languages and we need contributors to achieve this goal! Read [this issue](https://github.com/riggraz/astuto/issues/121) to see which locales are already available and which needs work. Also check out [this section](#translations) if you want to know more about how locales files are organized.
- **Coding**: [open a pull request](https://github.com/riggraz/astuto/pulls) with your bug fix or feature implementation. Before diving into coding, you may find [the coding and testing section](#coding-and-testing) useful.
[Open a new issue](https://github.com/riggraz/astuto/issues/new) on GitHub. In doing so, please follow these guidelines:
If you still have any doubt, feel free to [join our Discord](https://discord.com/invite/SrtUMRp) and drop a message! And remember: there are no stupid questions 😉
- Check whether this bug has been reported before in the [issues panel](https://github.com/riggraz/astuto/labels/bug). If that's the case, consider posting a comment to that already open issue, or react to a comment you agree with (for example, with the 👍 emoji). Otherwise, open a new issue.
- Choose a short, meaningful title
- Start the issue description with a quick summary of the problem you encountered
- Include steps to reproduce the issue
- State how you expected the program to behave, and how it actually behaved
- If applicable, write down stuff you tried to solve the problem that didn't work
- Feel free to include personal thoughts about why you think this issue is occurring
## Translations
### Proposing features
Locales are stored in YAML files under `config/locales`. Translations are splitted in 3 files:
As for bug reports, we use GitHub issues to track feature requests. So, if you want to propose a feature or enhancement, just [open a new issue](https://github.com/riggraz/astuto/issues/new). As always, check whether that feature has already been proposed before posting. If the issue is already there, just comment or add a reaction to express that you'd like this feature too.
- `[lang].yml`: the main locale file. Contains translation strings for the frontend, backend, mailers, etc.
- `activerecord/activerecord.[lang].yml`: contains Rails ActiveRecord translations, i.e. translations for model names, properties and validation error messages.
- `devise/devise.[lang].yml`: contains translations for the authentication system (which is based on Devise gem). It is likely that you'll find ready-made translations for your language at [this page](https://github.com/heartcombo/devise/wiki/I18n), so this step usually consist in a simple copy-paste!
### Coding
## Coding and testing
In order to contribute code, you should use the usual GitHub fork workflow. See [this section](#workflow) if you aren't comfortable with it yet.
First of all, you need to follow [the installation instructions](https://github.com/riggraz/astuto#installation) to have a working local instance of Astuto.
The following is a list of some guidelines to take into consideration when contributing code:
### Technologies
- If you're going to fix a bug or implement a feature that has already been documented with an issue, please let the community know by posting a comment on that issue. In this way, we avoid the (unfortunate) possibility of two people working on the same thing at the same time.
- If you want to fix a bug or implement a new feature that hasn't already been documented with an issue, please [open an issue](https://github.com/riggraz/astuto/issues/new) before.
- Follow styleguides for both [commit messages](#git-commit-messages) and [code](#coding-conventions)
- When you're done, open a pull request and explain clearly what it is about. We also encourage you to link to the issue it fixes.
Depending on the task you're working on, you need to know one or more of these technologies:
### Getting involved in the community
- [Ruby on Rails](https://rubyonrails.org/): Ruby framework for the backend
- [React](https://reactjs.org/): UI library used for most of the frontend views
- [Redux](https://redux.js.org/): state management library for React
- [TypeScript](https://www.typescriptlang.org/)
We'd love to hear your opinion both on small feature additions and on long-term strategic discussions. Indeed, you can contribute to Astuto just by dropping a comment to let us know your point of view.
### Project structure
In particular, some [issues](https://github.com/riggraz/astuto/issues?q=is%3Aissue+is%3Aopen+label%3Adiscussion) and [pull requests](https://github.com/riggraz/astuto/pulls?q=is%3Aopen+is%3Apr+label%3Adiscussion) are labeled "discussion". That label signifies that further discussion is required to move forward the development process: thus, we encourage you to express your opinion especially on these topics.
The project is broadly structured as follows:
## Styleguides
- `app`
- `models`: Rails ActiveRecord models. These models are mapped by ActiveRecord to database tables.
- `controllers`: Rails controllers. Web requests will be handled here. Here you can query the database, return HTML/JSON, etc. We try to keep controllers as small as possible.
- `views`: Rails views. Some of these views render HTML directly, whereas others render React components. Ideally, we'd like to move the entire frontend to React.
- `javascript`
- `actions`: Redux actions
- `components`: React components
- `containers`: React components that connect to Redux state. See [this article](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) to learn more.
- `reducers`: Redux reducers
- `stylesheets`: all CSS files are stored here
- `mailers`: mail templates that are sent to notify users
- `workflows`: classes that contains some complex logic. Usually that logic was originally in a controller, but has been refactored and delegated to a workflow. In fact, workflows are usually called inside controllers.
- `policies`: policies used by [Pundit](https://github.com/varvet/pundit) for resource authorization
- `config`
- `locales`: locales files for internationalization. See [this section](#translations) for additional information.
- `routes.rb`: backend routes, i.e. mapping requests to controller actions
- `db`
- `migrate`: contains migration files
- `schema.rb`: database schema
- `spec`: RSpec tests
### Git commit messages
### Specs (tests)
```
Short summary of the commit
Tests are done using RSpec, a testing framework for Ruby on Rails:
More throughout explaination of what the commit does and the reasoning behind it (optional)
```
For commit messages, please follow these broad guidelines:
- Separate subject from body with a blank line
- The subject must use present tense ("Add feature" not "Added feature") and imperative mood ("Fix bug" not "Fixes bug")
- Limit the subject to about 72 characters
- Try to be both coincise and clear
### Coding conventions
#### General coding conventions
- Write clean code
- We strongly encourage to write specs associated to the feature you're adding
#### Ruby coding conventions
TODO
#### JavaScript coding conventions
TODO
## This is my first contribution! Help!!
First off, we want to clarify that you don't need to be an expert or anything like that to contribute. There are [various ways](#how-to-contribute) in which you can contribute and we appreciate all kind contributions: huge ones as well as small ones, code contributions as well as documentation contributions.
Moreover, we understand that contributing to open source software may feel overwhelming at first (we've been there too!). But fear not, we're here to help you get started!
This section contains tips to help absolute beginners making their first contribution.
### Workflow
We follow the usual GitHub workflow for contributions:
1. [Open an issue](https://github.com/riggraz/astuto/issues/new) for the bug you're fixing or the feature you're developing, or, if the issue already exists, post a comment there
2. Fork this repository
3. Create a new branch in your forked repository
4. Code code code! (And test test test!)
5. When you're done, ensure that the test suite is running successfully
6. Submit a pull request against the master branch of this repository
If you are new to this workflow, we suggest you to deepen your knowledge by reading more about it, for example [this article](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
### Look for label "good first issue"
You'll find some issues labeled with "good first issue". These are issues that are pretty easy to solve, so we recommend tackling one of them if this is the first time you contribute. You can find "good first issues" by going to the issues panel and apply a filter, or by [clicking here](https://github.com/riggraz/astuto/labels/good%20first%20issue).
### Any doubt?
If you still have any doubt, feel free to [join our Discord](https://discord.gg/jTAgJvT8) and drop a message!
## Community
### Code of Conduct
The project and everyone involved in it is governed by [our code of conduct](https://github.com/riggraz/astuto/blob/master/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
### Language
The development language is English. This means that comments, variable/function/etc. names, issues, pull requests, documentation, etc., must be written in English.
We also encourage to write in simple English, by avoiding difficult and complex terms, since not everyone in the community is a native English speaker.
### Want to chat?
If you want to reach out to ask something or just to have a chat, feel free to message us on [our Discord channel](https://discord.gg/jTAgJvT8). If you want to report a bug or propose a feature, please use GitHub issues instead.
## Credits
This document has been inspired by the following contribution guidelines:
- [Berty Contribution Guidelines](https://github.com/berty/community/blob/master/CONTRIBUTING.md)
- [Atom Contribution Guidelines](https://github.com/atom/atom/blob/master/CONTRIBUTING.md)
Commit message guidelines have been adapted from [Robert Painsi Commit Message Guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53).
- To execute all specs, run `rspec` command inside the `web` container. System specs relies on Google Chrome to run, so you may need to rebuild Astuto image uncommenting lines 9-11 in Dockerfile.
- If you want to run all specs except for system specs, you can run the script `script/rspec-no-system-specs.sh`.

59
README.md
View File

@@ -6,38 +6,21 @@
<a href="https://www.producthunt.com/posts/astuto?utm_source=badge-top-post-badge&utm_medium=badge&utm_souce=badge-astuto" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=179870&theme=dark&period=daily" alt="Astuto - An open source customer feedback tool 🦊 | Product Hunt Embed" style="width: 250px; height: 54px;" width="250px" height="54px" /></a>
</p>
<h2 align="center"><a href="http://65.21.148.99:3000/">🦊 Try the demo out 🦊</a></h2>
---
- [What is Astuto?](#what-is-astuto)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Post-installation notes](#post-installation-notes)
- [Contributing](#contributing)
---
<h3 align="center"><a href="http://65.21.148.99:3000/">Try the demo out</a></h3>
<h5 align="center">To login as administrator:<br />email: admin@example.com | pass: password</h5>
## What is Astuto?
Astuto is a free, open source, self-hosted customer feedback tool. It helps you collect, manage and prioritize feedback from your users.
It has been heavely inspired by [Canny.io](https://canny.io/) ("astuto", indeed, is the italian translation of the word "canny"). If you want to try Astuto out there is a temporary demo <a href="http://65.21.148.99:3000/">available here</a>.
Astuto is a free, open source, self-hosted customer feedback tool. It helps you collect, manage and prioritize feedback from your users. It has been heavely inspired by [Canny.io](https://canny.io/) ("astuto", indeed, is the italian translation of the word "canny").
<img src="./images/featured-image.png" />
## Features
* Collect and manage feedback
* Boards, to divide different types of feedback
* Roadmap, to let your users know what you're working on
* Comments, to discuss with your customers
* Notifications, to inform post owner of comments
* Feedback labels, to inform about the state of a certain feedback
* Feedback updates, to notify your users with news regarding a certain feedback
* Completely customizable (i.e. you can add/edit/remove as many boards, feedback statuses as you want; you can configure the roadmap the way you want; etc.)
* Admin panel (multiple admins/moderators allowed)
* Dark mode
* Create custom boards and statuses, to better organize feedback
* Customize your roadmap, to let your users know what you're working on
* Many more...
## Requirements
@@ -48,23 +31,31 @@ It has been heavely inspired by [Canny.io](https://canny.io/) ("astuto", indeed,
**Note**: it is strongly suggested to run Astuto on Linux or macOS. As of today, Windows is likely to [cause problems](https://github.com/riggraz/astuto/wiki/Common-problems#standard_init_linuxgo211-exec-user-process-caused-no-such-file-or-directory). If you want to try anyway, follow along with the [Windows users installation guide](https://github.com/riggraz/astuto/wiki/Installation-for-Windows-users).
1. Ensure that you have the required software installed.
2. Clone this repository.
3. In Astuto's root directory, create a file named `.env` and fill it with the required environment variables (see `.env-example` for an example and check [this wiki page](https://github.com/riggraz/astuto/wiki/Required-environment-variables) for an explanation of the variables).
4. Run `script/docker-update-and-run.sh`.
5. You should now have a running instance of Astuto at `localhost:3000`. A default user account has been created with credentials email: `admin@example.com`, password: `password`.
### Manual (for development)
1. Clone this repository.
2. In Astuto's root directory, create a file named `.env` and fill it with the required environment variables (see `.env-example` for an example and check [this wiki page](https://github.com/riggraz/astuto/wiki/Required-environment-variables) for an explanation of the variables).
3. Run `script/docker-update-and-run.sh`.
4. You should now have a running instance of Astuto at `localhost:3000`. A default user account has been created with credentials email: `admin@example.com`, password: `password`.
### Using DockerHub image (fastest)
Coming soon!
## Post-installation notes
* **If you run into any problems take a look at the [common problems page](https://github.com/riggraz/astuto/wiki/Common-problems)**.
* When you want to launch Astuto you have to run `script/docker-run.sh`. If you installed new gems, packages or updated the database schema, you first need to run `script/docker-update.sh` and then `script/docker-run.sh`. You can run them together with `script/docker-update-and-run.sh`.
* You can always run `script/docker-update-and-run.sh` if unsure whether you should update or not. However, please note that `script/docker-update-and-run.sh` takes more time to run than `script/docker-run.sh`.
* If you changed some environment variables in `.env` you have to restart the instance for these changes to take effect.
## Contributing
Astuto is licensed under the [GNU GPLv3](https://github.com/riggraz/astuto/blob/master/LICENSE) license. You are welcome to contribute:
* Join the [Discord channel](https://discord.gg/SrtUMRp) to get in touch.
* You should take a look at the [technologies](https://github.com/riggraz/astuto/wiki/Technologies) used to build Astuto.
* You can run the test suite by typing `rspec` inside the `web` container. Before you can run `rspec`, you need to uncomment the Google Chrome installation lines in `docker/app/Dockerfile` and run `./script/docker-update-and-run.sh`.
* If you just have some suggestions you can [create an issue](https://github.com/riggraz/astuto/issues), [email us directly](mailto:riccardo.graziosi97@gmail.com) or [text us in our Discord server](https://discord.gg/SrtUMRp).
You are welcome to contribute:
* Read our [contributing guidelines](https://github.com/riggraz/astuto/blob/main/CONTRIBUTING.md)
* Join the [Discord channel](https://discord.gg/SrtUMRp) to get in touch
A huge thank you to all people who contributed:
<a href="https://github.com/riggraz/astuto/graphs/contributors">
<img src="https://contrib.rocks/image?repo=riggraz/astuto" />
</a>