Sing for Needs is a donation platform, meant to be a positive means for giving, inspired by music performances from artists, unknown and famous. The Artists get to see and choose the various causes to support with their performances, while getting a view of all the funds generated.
The Sing for Needs project is currently under active developement by a team of volunteers at Agileventures, an official UK Charity (#1170963) dedicated to crowdsourced learning and project development. Under the umbrella of Championer projects, the Sing for Needs backend uses the Elixir/Phoenix framework, while the frontend uses React, mainly to facilitate mentorship for the volunteers to learn these modern technologies.
This is a guide, to help easily get set up and started with the frontend, for any voluteer who would like to contribute through code, PR reviews, mentorship, or in any other way.
This describes how to contribute to SFN-CLIENT: the tools we use to track and coordinate the work that is happening and that needs to happen. This also describes the workflow -- the processes and sequences for getting contributions merged into the project in an organized and coherent way.
We use Zenhub to manage our work on features, chores and bugfixes.
We keep our code on GitHub and use git for version control.
Most of our developers use vs code and we really recommend it as an IDE for this project. Once you have it installed, be sure to set es-lint as your linter and enable format on save so that your code can be formated as soon as you save. Please ensure that the eslint you install is the same one in the image below
Search for and select eslint.autoFixOnSave in the settings (or add it as a true property in settings.json) as shown below
Each developer will usually work with a fork of the main repository on Agile Ventures. Before starting work on a new feature or bugfix, please ensure you have synced your fork to upstream/develop:
Please ensure you have nvm installed in your local machine. If you are using OSX you can run the command below
brew install nvm
Run the following command to install and switch to the current node version for the project:
nvm install v10.13.0
To ensure that the correct node version for the project is automatically selected when you cd into the sfn-client project's directory please install avn in your local machine and run the commands below in your terminal:
npm install -g avn avn-nvm avn-n
OR
yarn global add avn avn-nvm avn-n
Then run:
avn setup
Unfortunately, if you are using vs code's integrated terminal, you have to cd .. and cd back in cd sfn-client
In Mac's Terminal it works automatically.
If you are using fish shell please use this to install nvm and install avn for fish
npm install -g yarn
yarn
The backend is currently deployed on gigalixir to enable Front end developers ease of setup. To get set up with the deployed backend:
- Create a
.env.localfile in the root of the app you just cloned - Add the following
REACT_APP_BASE_URL = 'http://localhost:4002'
REACT_APP_SFN_BACKEND = 'https://sing-for-needs.gigalixirapp.com/graphiql'
SKIP_PREFLIGHT_CHECK=true
Please note that the REACT_APP_BASE_URL variable is meant to be the base REST API endpoint for the application. Also you can choose to clone the backend and get setup locally.
yarn start
-
You may need to set up
.env.localwith your backend server's base URL. This can be easily done by coppying the content of your.env.defaultfile to.env.localas shown belowcp .env.default .env.local -
Update the value of the
REACT_APP_BASE_URLto correspond to your server URL e.g.REACT_APP_BASE_URL = 'http://localhost:4000'
-
This codebase uses Enzyme Javascript Testing Utility. To learn more about the Enzyme you can checkout their documentation.
-
start the test by running
yarn test -
then press
ato run all test
-
You can't commit or run the tests if you have lint errors, so run:
yarn lint:fix
- Ensure you have docker installed. Install docker
-
Change to the project root directory. (.//sfn-client)
-
Create an image with the following command
docker build -f docker/Dockerfile -t sfn_client:production .
-
Run the created image with
docker run -p 80:80 sfn_client:production
-
Access the application on localhost port 80
- If tests are failing, or you found a bug running the development server, you can debug using the inline debug tool.
- You can create an issue by clicking on this link or by clicking on the new issue button on for github issues for the sfn-client project
- Click on the Get Started button to open the issue creation template.
- Fill in all the relevant sections provided in the template as you create your issue.
- Submit your issue by clicking on "Submit issue" button.
When deciding on an issue to work on, look for the Help Wanted or Good First Issue tags.
Request to be added as a collaborator in our AgileVentures.org Slack chat channel.
After you’re a collaborator, you can move the ticket to the In Progress column here, to indicate you’ve started work on it.
git checkout develop
git pull upstream develop
After you pulled the latest develop branch, make sure you have also the dependencies installed each time, by running in the console:
yarn
Ensure you have setup AgileVentures/sfn-client's upstream develop. Otherwise you will not have the latest develop changes.
To confirm this, run git remote -v.
You should see a simillar output.
origin  https://github.com/yourgithubusername/sfn-client.git (fetch)
origin  https://github.com/yourgithubusername/sfn-client.git (push)
upstream    https://github.com/AgileVentures/sfn-client.git (fetch)
upstream    https://github.com/AgileVentures/sfn-client.git (push)
If not, you need to set the remote develop in order to get the latest copy once changes are merged.
In order to achieve that, run:
git remote add upstream https://github.com/AgileVentures/sfn-client
git pull upstream develop
This depends on the name of your origin (Counter check before running the above command).
You will now have the latest copy of develop in your local.
Once this is done, you can proceed with naming your branch following the below convention.
git checkout -b 17-add-sfn-logo
Where 17 is the ticket number and add-sfn-logo is a short description of the purpose of your branch.
Ensure your commit message clearly communicate the work you have done.
For example,
git commit -m "Implement user login"
After feature branch work is complete, push up to the upstream repo, for example:
git push --set-upstream upstream 17-add-sfn-logo
For your Pull Requests, ensure you have a proper title describing your task. Make sure to add a link to the ticket you've worked on and add any screenshots if necessary.
In your pull request description please include a sensible description of your code and a tag fixes #<issue-id> e.g. :
This PR adds a CONTRIBUTING.md file and a docs directory
fixes #799
which will associate the pull request with the issue in the Zenhub board.
Your pull request needs to be reviewed by at least two people in the team for it to be merged in develop branch.
Instructions on how to review a pull request can be found here.
The Sing for Needs project follows user-centered design principles, accordingly the platform is built with the different key personas (artists, donors and the people behind causes) in mind. Imagine as these personas are the key stakeholders of the project.
If you want to introduce a new feature, then your responsibility is to consult each of the personas mentioned above, and empathize with their jobs-to-do, major pains and major gains to properly use this knowledge to shape the new feature. The personas documentation gives additional guidance how you can immerse yourself in the topic.
We try to make designing components easier with setting up some base grounds of colors, typography and layouts. Before start designing a component for the page, please consult these materials. You can find them in the src/components/styles directory.
The layout of the pages is following Bootstrap's 12 column grid system, but with using CSS Grid and Flexbox together. We recommend to have a look at the documentation, or just give a shot to grid garden game.
The structure of the components and spacing is suggested to follow an 8px grid system, what does that mean? It means every spacing, padding and size (width, height) of a component is following a multiple of 8. To give you a head start related to this rule, we set up the margins and paddings already to use in the styles/utilities.scss file as SASS variables.
We use BEM (stands for Block-Element-Modifier) which is a naming convention standard for CSS class names. It has fairly wide adoption and is immensely useful in writing CSS that is easier to read, understand, and scale.
A BEM class name includes up to three parts:
- Block: The outermost parent element of the component is defined as the block.
- Element: Inside of the component may be one or more children called elements.
- Modifier: Either a block or element may have a variation signified by a modifier.
- If all three are used in a name it would look something like this:
[block]__[element]--[modifier]
For full reference with examples, please consult this amazing article. If you see something different in our codebase than the best practises mentioned in the article, please open a new issue!
In 2019 we've created a simple branding document to establish the basis for the design in terms of colors, typography and photographic direction. The values for typography and colors will be reflected in the .scss variables ($variable) as well.
Before delivering a final UI for screens, please consult this little guidance and the stylesheets (src/styles) if all the aspects are right in the designs. It's worth checking back because the branding document will evolve in time, so changes will occur.
As moving towards with the project the individual screens that are in-progress and assets will be documented here. Wireframes which have been implemented already are under the documentation/wireframes/finished folder.
For more mockups that have been used in this project, please follow this link