diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 0000000000..a8c182a6b2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -0,0 +1,17 @@ +--- +name: 'Bug Report: Issues with Chapter software' +about: Report an issue or flaw in chapter software's schema, +architecture, APIs, UI or anything related to our software. +title: '' +labels: 'type: bug' +assignees: '' + +--- + +### Describe the bug: +Please describe the bug in as much detail as possible. + + +### Tell us about your browser and operating system: +- **Browser(s) name and version**: +- **Operating System**: diff --git a/.github/ISSUE_TEMPLATE/discussion.md b/.github/ISSUE_TEMPLATE/discussion.md new file mode 100644 index 0000000000..b260f26b54 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/discussion.md @@ -0,0 +1,11 @@ +--- +name: 'Discussion: Discuss ideas for the Chapter project' +about: This is for discussing ideas, features, UI/UX design, libraries, frameworks, APIs and for sharing your views on the project. +title: '' +labels: 'type: discussion' +assignees: '' + +--- + +### Discuss your ideas or share your views: +Make sure to tell how your idea will benefit this project. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..ef3c254493 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,12 @@ + + +- [ ] I have read [Chapter's contributing guidelines](https://github.com/freeCodeCamp/chapter/blob/master/CONTRIBUTING.md). +- [ ] My pull request has a descriptive title (not a vague title like `Update README.md`). +- [ ] My pull request targets the `master` branch of Chapter. + + + +Closes #XXXXX + + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..afa841621e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1 @@ +**Our Code of Conduct is available here: https://code-of-conduct.freecodecamp.org/** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cb07f7e38..d8da1407fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,269 @@ # Contribution Guidelines -Hello. 👋 +Hello. :wave: -Welcome to Chapter, the newest project for freeCodeCamp. We are glad you are here. +Welcome to Chapter, the newest project by freeCodeCamp. We are glad to see your interest in this project. We strictly enforce our ["Code of Conduct"](https://www.freecodecamp.org/code-of-conduct). Please take a moment to read it. It's only 196 words long. -Happy contributing. +You should [join our Discord server](https://discord.gg/vbRUYWS) to get connected with people interested in this project and to be aware of our future announcements. -## We are just getting started +## Here are some ways to help us -Implementation details are still being discussed and the project is currently at a very early stage. The stage of the project is changing on a daily basis, thoughts and ideas are being contributed at a very high pace. +### 1. Take part in discussions and tell us your views -## What do we need help with right now? +Implementation details are still being discussed and the project is currently at a very early stage. The stage of the project is changing on a daily basis, thoughts and ideas are being contributed at a very high pace. -We are in the very early stages of development on this new application. We value your insight and expertise. In order to prevent duplicate issues, please search through our existing issues to see if there is one for which you would like to provide feedback. We are currently trying to consolidate many of the issues based on topics like documentation, user interface, API endpoints, and architecture. +Keep in mind that our focused discussions takes place here on GitHub issue threads. We encourage you to take part in the discussions on topics you find interesting: -## How to submit an issue +- [Introduce yourself and volunteer your skills](https://github.com/freeCodeCamp/chapter/issues/11) +- [Next Steps](https://github.com/freeCodeCamp/chapter/issues/47) +- [Feature Dev / Stories](https://github.com/freeCodeCamp/chapter/issues) +- [Tech Stack](https://github.com/freeCodeCamp/chapter/issues/2) +- [Shared Profile Data & Auth Across Collectives](https://github.com/freeCodeCamp/chapter/issues/40) +- [Discovery and Searching Across Collective Instances](https://github.com/freeCodeCamp/chapter/issues/33) +- [Accessibility](https://github.com/freeCodeCamp/chapter/issues/65) +- [API](https://github.com/freeCodeCamp/chapter/issues/17) +- [Documentation](https://github.com/freeCodeCamp/chapter/issues/12) +- [Mobile App](https://github.com/freeCodeCamp/chapter/issues/20) +- [UX - Design Landing page](https://github.com/freeCodeCamp/chapter/issues/5) +- [Internationalization / Translation](https://github.com/freeCodeCamp/chapter/issues/21) +- [Ideas for Version 1 or Version 2 of the App](https://github.com/freeCodeCamp/chapter/issues/1) -- Search through current issues to verify that you are not creating a duplicate issue. -- Use the issue template as a guide to tell us more about your issue: - - **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. +If you can't find what you were looking for in the above topics then feel free to [open a new issue](https://github.com/freeCodeCamp/chapter/issues/new/choose) to share your views or to report bugs. - - **Describe alternatives you've considered** - A clear and concise description of any alternative solutions or features you've considered. +Before opening a new issue please search through current issues to verify that you are not creating a duplicate issue. - - **Additional context** - Add any other context or screenshots about the feature request here. +### 2. Contribute to this open source codebase -- Be as descriptive as possible. +If you feel ready to contribute code to this project then you should follow the below steps: -## Working on a change +#### Step 1: Fork the repository on GitHub -- Create a new branch on your fork: `git checkout -b your-branch-name` -- Use the GitHub editor or your local environment to make your changes -- Push your changes to the branch you created on your fork: `git push origin your-branch-name` +['Forking'](https://help.github.com/articles/about-forks/) is a step where you get your own copy of Chapter's repository (a.k.a repo) on GitHub. -## How to submit a pull request +This is essential as it allows you to work on your own copy of Chapter. It allows you to request changes to be pulled into the Chapter's repository from your fork via a pull request. -- After working on changes and pushing to your fork of the repo, create a pull request on your fork. -- Complete the PR template: - - You have read the contribution guidelines - - Your pull request uses a descriptive title (not a vague title like `update.md`) - - Your pull request targets the master branch of chapter - - Closes #XXXXX -- Verify that no changes need to be made or merge conflicts exist. -- Submit the request and wait for approval from a project maintainer. -- Congratulations! You submitted a PR. +Follow these steps to fork the `https://github.com/freeCodeCamp/chapter` repository: +1. Go to the Chapter repository on GitHub: . +2. Click the "Fork" Button in the upper right-hand corner of the interface ([Need help?](https://help.github.com/articles/fork-a-repo/)). +3. After the repository has been forked, you will be taken to your copy of the Chapter repository at `https://github.com/YOUR_USER_NAME/chapter`. -## I found a typo. Should I report an issue before I can make a pull request? +![an image illustrating the fork button](docs/images/how-to-fork.png) -For typos and other wording changes, you can directly open pull requests without first creating an issue. Issues are more for discussing larger problems associated with code or structural aspects of the application +#### Step 2: Preparing the development environment -## I am new to GitHub and Open Source, where should I start? +Install [Git](https://git-scm.com/) and a code editor of your choice. We recommend using [VS Code](https://code.visualstudio.com/). + +Clone your copy of Chapter. ['Cloning'](https://help.github.com/articles/cloning-a-repository/) is where you download a copy of the repository from a `remote` location to your local machine. Run these commands on your local machine to clone the repository: + +1. Open a Terminal in a directory where you would like the Chapter project to reside. + +2. Clone your fork of Chapter, make sure you replace `YOUR_USER_NAME` with your GitHub username: + + ```sh + git clone https://github.com/YOUR_USER_NAME/Chapter.git + ``` + +This will download the entire Chapter repository to your directory. + +Now that you have downloaded a copy of your fork, you will need to set up an `upstream`. The main repository at `https://github.com/freeCodeCamp/chapter` is often referred to as the `upstream` repository. Your fork at `https://github.com/YOUR_USER_NAME/chapter` is often referred to as the `origin` repository. + +You need a reference from your local copy to the `upstream` repository in addition to the `origin` repository. This is so that you can sync changes from the `upstream` repository to your fork which is called `origin`. To do that follow the below commands: + +1. Change directory to the new chapter directory: + + ```sh + cd chapter + ``` + +2. Add a remote reference to the main chapter repository: + + ```sh + git remote add upstream https://github.com/freeCodeCamp/chapter.git + ``` + +3. Ensure the configuration looks correct: + + ```sh + git remote -v + ``` + + The output should look something like below: + ```sh + origin https://github.com/YOUR_USER_NAME/chapter.git (fetch) + origin https://github.com/YOUR_USER_NAME/chapter.git (push) + upstream https://github.com/freeCodeCamp/chapter.git (fetch) + upstream https://github.com/freeCodeCamp/chapter.git (push) + ``` + +#### Step 3: Making changes to Chapter codebase :fire: + +> **Note: Always follow the below steps before you start coding or working on an issue.** + +You are now almost ready to make changes to files but before that you should **always** follow these steps: + +1. Validate that you are on the `master` branch + + ```sh + git status + ``` + + You should get an output like this: + ```sh + On branch master + Your branch is up-to-date with 'origin/master'. + + nothing to commit, working directory clean + ``` + + If you are not on master or your working directory is not clean, resolve any outstanding files/commits and checkout `master`: + ```sh + git checkout master + ``` + +2. Sync the latest changes from the chapter upstream `master` branch to your local master branch. This is very important to avoid conflicts later. + + > **Note:** If you have any outstanding Pull Request that you made from the `master` branch of your fork, you will lose them at the end of this step. You should ensure your pull request is merged by a moderator before performing this step. To avoid this scenario, you should *always* work on a branch separate from master. + + This step **will sync the latest changes** from the main repository of chapter. + + Update your local copy of the freeCodeCamp upstream repository: + ```sh + git fetch upstream + ``` + + Hard reset your master branch with the chapter master: + ```sh + git reset --hard upstream/master + ``` + + Push your master branch to your origin to have a clean history on your fork on GitHub: + ```sh + git push origin master --force + ``` + + You can validate if your current master matches the upstream/master or not by performing a diff: + ```sh + git diff upstream/master + ``` + + If you don't get any output, you are good to go to the next step. + +3. Create a fresh new branch + + Working on a separate branch for each issue helps you keep your local work copy clean. You should never work on the `master` branch. This will soil your copy of chapter and you may have to start over with a fresh clone or fork. + + Check that you are on `master` as explained previously, and branch off from there by typing: + ```sh + git checkout -b fix/update-readme + ``` + + Your branch name should start with `fix/`, `feat/`, `docs/`, etc. Avoid using issue numbers in branches. Keep them short, meaningful and unique. + + Some examples of good branch names are: + ```md + fix/update-nav-links + fix/sign-in + docs/typo-in-readme + feat/sponsors + ``` + +4. Edit files and write code on your favorite editor. Then check and confirm the files you are updating: + + ```sh + git status + ``` + + This should show a list of `unstaged` files that you have edited. + ```sh + On branch feat/documentation + Your branch is up to date with 'upstream/feat/documentation'. + + Changes not staged for commit: + (use "git add/rm ..." to update what will be committed) + (use "git checkout -- ..." to discard changes in working directory) + + modified: CONTRIBUTING.md + modified: README.md + ... + ``` + +5. Stage the changes and make a commit + + In this step, you should only mark files that you have edited or added yourself. You can perform a reset and resolve files that you did not intend to change if needed. + + ```sh + git add path/to/my/changed/file.ext + ``` + + Or you can add all the `unstaged` files to the staging area using the below handy command: + + ```sh + git add . + ``` + + Only the files that were moved to the staging area will be added when you make a commit. + + ```sh + git status + ``` + + Output: + ```sh + On branch feat/documentation + Your branch is up to date with 'upstream/feat/documentation'. + + Changes to be committed: + (use "git reset HEAD ..." to unstage) + + modified: CONTRIBUTING.md + modified: README.md + ``` + + Now, you can commit your changes with a short message like so: + + ```sh + git commit -m "fix: my short commit message" + ``` + + We highly recommend making a conventional commit message. This is a good practice that you will see on some of the popular Open Source repositories. As a developer, this encourages you to follow standard practices. + + Some examples of conventional commit messages are: + + ```md + fix: update API routes + feat: RSVP event + fix(docs): update database schema image + ``` + Keep your commit messages short. You can always add additional information in the description of the commit message. + +6. Next, you can push your changes to your fork. + + ```sh + git push origin branch-name-here + ``` + + For example if the name of your branch is `fix/signin` then your command should be: + ```sh + git push origin fix/signin + ``` + +#### Step 4: Proposing a Pull Request (PR) + +After you've committed and pushed changes to your fork, check here for [how to open a Pull Request](/docs/how-to-open-a-pull-request.md). + +## Frequently Asked Questions + +### What do we need help with right now? + +We are in the very early stages of development on this new application. We value your insight and expertise. In order to prevent duplicate issues, please search through our existing issues to see if there is one for which you would like to provide feedback. We are currently trying to consolidate many of the issues based on topics like documentation, user interface, API endpoints, and architecture. Please [join our Discord server](https://discord.gg/vbRUYWS) to stay in the loop. + +### I found a typo. Should I report an issue before I can make a pull request? + +For typos and other wording changes, you can directly open pull requests without first creating an issue. Issues are more for discussing larger problems associated with code or structural aspects of the application. + +### I am new to GitHub and Open Source, where should I start? Read our [How to Contribute to Open Source Guide](https://github.com/freeCodeCamp/how-to-contribute-to-open-source). @@ -66,3 +274,5 @@ When in doubt, you can reach out to current project lead(s): | Name | GitHub | Twitter | |:----------------|:-------|:--------| | Quincy Larson | [`@QuincyLarson`](https://github.com/QuincyLarson) | [`@ossia`](https://twitter.com/ossia)| + +You are a champion :). diff --git a/README.md b/README.md index 9e80df205a..1fa151b4ce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## Welcome to Chapter +# Welcome to Chapter After several years of being dissatisfied with existing group event tools (Meetup, Facebook events) we decided to build our own. @@ -8,9 +8,16 @@ Your nonprofit can sub-domain it to your website like `chapter.sierraclub.org` o You can use your own authentication tools. And all your user data will stay on your own server. -### Tech stack +To better communicate and more easily build an API and UI, we've decided on a collection of terminology to discuss about the Chapter project in a clear way: -We're planning to use the following tools: +- `collective` is one singular instance/deployment of Chapter. For e.g., Women who Code at the domain `chapter.womenwhocode.com`. +- `user` is a person who authed to the chapter. +- `chapter` is a container for events, with a description and subscribers, and one or more admins who can manage it. For e.g., Women who Code NYC. +- `event` is a single meetup that users can RSVP to, has a specific location and time, and has organizers. For e.g., Women who Code NYC April Meet. + +## Tech stack + +We are planning to use the following tools: - [Node.js](https://nodejs.org) / [Express](https://expressjs.com) for our backend - [Postgres](https://www.postgresql.org) with [Sequelize](https://sequelize.org) @@ -23,48 +30,15 @@ We are considering using a tool like [Next.js](https://nextjs.org) to get up and We will focus on building an open API first. Then developers can use the API to build their own mobile clients and voice interface clients. -### Quick Links - -- [Tech Stack (Closed)](https://github.com/freeCodeCamp/chapter/issues/2) -- [Next Steps](https://github.com/freeCodeCamp/chapter/issues/47) -- [Feature Dev / Stories](https://github.com/freeCodeCamp/chapter/issues) -- [API](https://github.com/freeCodeCamp/chapter/issues/17) -- [Documentation](https://github.com/freeCodeCamp/chapter/issues/12) -- [Shared Profile Data & Auth Across Collectives](https://github.com/freeCodeCamp/chapter/issues/40) -- [Discovery and Searching Across Collective Instances](https://github.com/freeCodeCamp/chapter/issues/33) -- [Mobile Apps](https://github.com/freeCodeCamp/chapter/issues/20) -- [UX - Design Landing page](https://github.com/freeCodeCamp/chapter/issues/5) -- [Internationalization / Translation](https://github.com/freeCodeCamp/chapter/issues/21) -- [Accessibility](https://github.com/freeCodeCamp/chapter/issues/65) -- [Ideas for Version 1 or Version 2 of the App](https://github.com/freeCodeCamp/chapter/issues/1) -- [Introduce Yourself / Volunteer Your Skills](https://github.com/freeCodeCamp/chapter/issues/11) - -### Terminology - -To better communicate and more easily build an API and UI, we've decided on a collection of terminology to describe Chapter in a clear way. - -- A "collective" is one singular instance/deployment of Chapter - *For example, Women who Code at the domain `chapter.womenwhocode.com`* -- A "user" is a person who authed to the chapter - *For example, Kognise* -- A "chapter" is a container for events, with a description and subscribers, and one or more "admins" who can manage it - *For example, Women who Code NYC* -- A "event" is a single meetup that users can RSVP to, has a specific location and time, and has "organizers" - *For example, Women who Code NYC April Meetup* - -(All of the above examples are fictional, meaningless, and probably super inaccurate) - -### Schema +## Schema ![a diagram illustrating the proposed schema for chapter](https://user-images.githubusercontent.com/2755722/66802465-7d181900-eeea-11e9-9c6a-48012839d5f2.png) -### User Stories so far +## User stories so far -Our goal is to keep things simple and not reinvent wheels. +Our goal is to keep things simple and not reinvent wheels. So far we have only two user roles: participants and group organizers. -So far we have only two user roles: participants and group organizers - -#### As a future participant +### As a future participant - I can use a search box on the landing page to input a city, state, or country name and it will autocomplete. I can click one of those locations. @@ -78,7 +52,7 @@ So far we have only two user roles: participants and group organizers - I can filter all events in my location by tag/interests. -#### As an organizer +### As an organizer - I can create a group. @@ -96,20 +70,28 @@ So far we have only two user roles: participants and group organizers - I can add a food sponsor to the event with a link to their website as a way of thanking them for food. -I can see how many times a participant has come to the event as well as their attendance rate - -### Roadmap +- I can see how many times a participant has come to the event as well as their attendance rate. -1. Design the schema -2. Set up the API endpoints -3. Build the web client and let other developers use the API to build mobile clients and voice interface clients +## Roadmap -Quincy Larson is the project lead. +1. Design the schema. +2. Set up the API endpoints. +3. Build the web client and let other developers use the API to build mobile clients and voice interface clients. -freeCodeCamp will start "dogfooding" this as soon as possible with several of its local study groups. +Quincy Larson is the project lead. freeCodeCamp.org will start "dogfooding" this as soon as possible with several of its local study groups. Here's an out-dated example of an app with similar functionality: [The freeCodeCamp Study Group Directory](https://study-group-directory.freecodecamp.org). -To ask a question or share an idea, create a GitHub issue on this repository. +You should [join our Discord server](https://discord.gg/vbRUYWS) to get connected with people interested in this project and to be aware of our future announcements. + +## Contributing + +### [Take part in discussions or Contribute code to this opensource codebase.](CONTRIBUTING.md) + +## License + +Copyright © 2019 freeCodeCamp.org + +The content of this repository is bound by the following license(s): -And join [our Discord server where we're chatting while we build this](https://discord.gg/vbRUYWS). +- The computer software is licensed under the [BSD-3-Clause](LICENSE) license. diff --git a/docs/how-to-open-a-pull-request.md b/docs/how-to-open-a-pull-request.md new file mode 100644 index 0000000000..97d88adc9b --- /dev/null +++ b/docs/how-to-open-a-pull-request.md @@ -0,0 +1,41 @@ +# How to open a Pull Request + +## How to prepare a good Pull Request title: + +When opening a Pull Request(PR), use the following scope table to decide what to title your PR in the following format: + +`fix/feat/chore/refactor/docs/perf (scope): PR Title` + +An example is `feat(client): night mode`. + +| Scope | Documentation | +|---|---| +| `api` | For Pull Requests making changes to the APIs, routes and its architecture | +| `db` | For Pull Requests making changes related to database | +| `client` | For Pull Requests making changes to client platform logic or user interface | +| `docs` | For Pull Requests making changes to the project's documentation | + +## Proposing a Pull Request (PR) + +1. Once the edits have been committed & pushed, you will be prompted to create a pull request on your fork's GitHub Page. Click on `Compare and Pull Request`. + + ![an image showing Compare & pull request prompt on GitHub](images/pull-request-prompt.png) + +2. By default, all pull requests should be against the Chapter main repo, `master` branch. + + ![ an image showing the comparison of forks when making a pull request](images/comparing-forks-for-pull-request.png) + +3. Submit the pull request from your branch to Chapter's `master` branch. + +4. In the body of your PR include a more detailed summary of the changes you made and why. + + - You will be presented with a pull request template. This is a checklist that you should have followed before opening the pull request. + + - Fill in the details as they seem fit you. This information will be reviewed and decide whether or not, your pull request is going to be accepted. + + - If the PR is meant to fix an existing bug/issue then, at the end of + your PR's description, append the keyword `closes` and #xxxx (where xxxx + is the issue number). Example: `closes #1337`. This tells GitHub to + automatically close the existing issue, if the PR is accepted and merged. + +You have successfully created a PR. Congratulations! :tada: diff --git a/docs/images/comparing-forks-for-pull-request.png b/docs/images/comparing-forks-for-pull-request.png new file mode 100644 index 0000000000..dd8558d1be Binary files /dev/null and b/docs/images/comparing-forks-for-pull-request.png differ diff --git a/docs/images/how-to-fork.png b/docs/images/how-to-fork.png new file mode 100644 index 0000000000..bcc2294cd8 Binary files /dev/null and b/docs/images/how-to-fork.png differ diff --git a/docs/images/pull-request-prompt.png b/docs/images/pull-request-prompt.png new file mode 100644 index 0000000000..7a28ef6dba Binary files /dev/null and b/docs/images/pull-request-prompt.png differ