UPDATED: 20200502
Thanks for checking out Activity. Activity is an open source project currently maintained by the team at Hikaya.
- Contributing to Hikaya
Before we get started, here are a few things we expect from you (and that you should expect from others):
- Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct.
- Activity Community Versions are released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.
- If you open a pull request, please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution.
- When adding content, please consider if it is widely valuable. Please don't add references or links to things you or your employer have created as others will do so if they appreciate it.
All contributors are welcome to submit issues and make pull requests to the repository.
- Look through the issues.
If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question. If you see none, feel free create an issue and ask for guidance on where to start.
- If you find an issue you would like to work on, feel free to assign it to yourself.
- If you don't find one you would like to work on, create an issue, assign a label and @mention one of the maintainers to let them know about the issue.
This repo is currently maintained by Hikaya, who have commit access. They will likely review your contribution. If you haven't heard from anyone in 5 days, feel free to bump the thread or @-mention a maintainer to review your contribution.
Long standing contributors will be given write access to the repository. In addition, we have slots for contributors to be given maintainer status which allows contributors to administer the repository, support the onboarding of new contributors, and influence the product roadmap.
Our current maintainers are: Peter Odeny (@odenypeter) and Isaac Kimaiyo (@Kimaiyo077).
- Determine how many hours you can commit to each week. Think about how many hours you can commit to each week. Currently many of our contributors spend around ~20-25 hours a week but there is no minimum, only that you set your own hours.
- Come up with your own weekly schedule and propose it to the team. If you have certain days and times you are tentatively available you can put together a schedule of what a typical week will look like so others can try and sync with you or know when to reach out on slack. These are just tentative and used by other contributors to coordinate calls between each other.
- Try to make at least one of the sprint calls each week (Monday and Saturday 7 PM EAT). If you can’t make a call, kindly write on the #sprint-planning slack channel or message me before hand so we can know if you are able to join or not. We just ask for communication courtesy but understand contributors won’t be able to make each call.
- Ask for help when you need it Our philosophy is to let contributors work on anything they think could add value to our apps. The core team at Hikaya will try to make themselves available to support any new onboarding or even have paired programming sessions on an issue to help you get started. We kindly ask all contributors to not be shy and ask for help when you need it.
- Be open and communicate If life has gotten busy or priorities have changed and you can no longer contribute, no worries, we completely understand! All we ask is for you to communicate and let us know upfront so we can plan accordingly. You're always welcome to pause and contribute another time.
- Set priorities for each sprint in coordination with the product and technical leads.
- Maintain and ensure consistent and proper use of the sprint board.
- Be a reviewer for many tasks. Clear communication will be done at the beginning of the sprint around which tasks will be reviewed by whom.
- “Coach” other members as they work on their tasks.
Discussions about Activity take place in the Issues sections for each repo, as well as on Spectrum. Anybody is welcome to join these conversations.
Thanks for contributing!
The team has a 6-12 month high-level product roadmaps (See Activity Roadmap) which defines epics and feature sets to be addressed during this period.
We will work in two-week Sprints on the items on the roadmap. At the end of each sprint, we want to have a stable release of Activity that can be shipped to our users. The work planned during a sprint is captured in the Task board. The feature sets of each sprint are highlighted in a published Release in Github.
A typical month
Week 1: Reduce debt introduced in the previous iteration, address critical issues uncovered in the previous iteration, and plan the next iteration.
Week 2: Work according to the milestone and minor release to
production.
Week 3+: Work according to the milestone and monitoring the minor release and fix critical issues.
Final Week: See
Hardening Sprint. The team improves test coverage by building tests and cleaning up unused code and templates. Deploy toproductionand showcase new features.
We follow a typical checklist before we ship new features:
✅Pull Requests are reviewed and merged to develop branch.
✅The PR is deployed to development environment and passes user acceptance testing (UAT).
✅Manually execute the Smoke Test on all supported platforms.
✅Release notes updated.
✅Deploy to production.
Before each Milestone, we will prioritize features to implement and bugs to fix in the upcoming iteration. Bugs and Defects are assigned to a sprint for the iteration and include steps to reproduce and current and expected behaviors. For new features, we create Tasks and include Acceptance Criteria.
We use the following definitions to track our issues:
- Bug: An issue that stop the user from doing what they intended.
- Defect: An issue that does not do what it was intended to do.
- Task: An issue that is an enhancement or new feature.
Current behavior
A clear and concise description of what the bug is.
Expected behavior
A clear and concise description of what you expected to happen.
To Reproduce:
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
Screenshots
If applicable, add screenshots to help explain your problem.
Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is.
Acceptance Criteria
A clear and concise description of how to ensure the feature request is met.
GIVEN I am a logged in user
AND I navigate to the main page...
AND I click on the button.
THEN I expect this to happen..
Additional context
Add any other context or screenshots about the feature requests.
Each issue card will have an Acceptance Criteria that defines the definition of done for every task that is worked on.
We use *Github Labels to describe the task card including its priority and complexity. Here is a list that we try to consistently use across all our applications:
| Label | Description |
|---|---|
Good first issue |
Good for newcomers |
bug |
Something isn't working |
defect |
Something isn't working right |
enhancement |
New feature |
dependencies |
Updates dependencies |
duplicate |
Issue or pull request exists |
help wanted |
Extra attention is required |
requires research |
Further information is required |
priority |
High priority issue |
design needed |
Requires a wireframe |
tests |
For unit and integration tests |
0 |
Insignificant task (minimal effort and time needed) |
1 |
Simple issues requiring minimal effort |
2 |
Not so complex, requiring a relatively good amount of effort and time to fix |
5 |
Complex task |
8 |
Very complex task |
Story point estimation
Story points are used to estimate the effort needed for each task. We try to avoid using time estimates and a more useful measurement for team capacity is the effort needed and then complexity of a task.
| Story Point | Complexity reference |
|---|---|
| 1 | Changing a label |
| 2 | Making a model change |
| 3 | Implementing CRUD on the UI |
| 5 | Implementing a new model |
| 8 | Introducing complex logic |
| 13 | Research task, building a proof of concept |
| 21 | Should be used sparingly |
We work toward a Sprint with the goal to release to production every two weeks. We use Github Milestones to track what issues contributors work on during a specific Sprint. Each milestone will have a start and end date and the product team will help to groom the issues and tag them to a specific sprint number before the sprint starts.
Each week we have two calls as a team to discuss our priorities and reflect:
- Sprint Planning: every Monday 7 PM EAT
- Sprint Review: every Saturday 7 PM EAT
Join calls using
Google Meetand follow the#sprint-planning channelon slack.
We use Github Projects to manage our current sprints with automated workflows. Each repo will have its own task board to manage issues and will consist of the following columns:
To doIn progressPull requestDev testingDone
Before every sprint, we archived all issues in the Done columns and add issue cards with the current sprint milestone tagged to them. During our sprint calls, the team will groom, discuss, and assign cards to contributors to work on.
Note:
- At the beginning of every milestone, we include all items in the
To dostage and move them over as we go.- At the end of a milestone, any issues in
To doorIn Progressneed to be moved over to the next sprint (if still relevant) or turned into new issues.
Bugs and features will be assigned a sprint, and within a sprint, they will be assigned a priority. The priority dictates the order in which issues should be addressed. An important bug (something that we think is critical for the milestone) is to be addressed before the other bugs.
The final week of the month is what we call the "Hardening Sprint". During this week we will fix the critical bugs and focus the entire week on improving test coverage by building unit and integration tests for any new features.
Note:
Currently since we have been refactoring the app, the upcoming hardening sprints will be focused on adding tests to existing features. Our plan is to go app by app and build test
During this period we make a build available on the insiders channel. We will monitor incoming issues from this release, fix any critical bugs that arise, and then produce a final stable release for the monthly iteration.
We perform QA testing when features are merged into develop. We use automated end-to-end testing to provide a strong foundation for functional testing.
Source control: Git
Source code: All our repositories are stored on GitHub.
Branches:
We use 3 main branches in all our repositories :
Dev (or Develop) - All bug fixes, defects, and tasks.
Feature branches: All feature branches must be named like 123-explanation-of-feature-fix, where 123 is the issue number on GitHub.
Master - Clean code in production environment
Note:
- All pull requests should be based off of the
developbranch.- All branch names should follow the issue number such as: ACT-001. The numbering should follow the auto-generated GitHub issue number.
We use Github to track Issues and Pull Requests for all our work. When making commits, please ensure that you have create a separate branch off of the main develop branch before you begin making changes to the source code. Feel free to make commits as often as possible to your branch. If the issue you are working on has been open for a few days, consider pulling in the latest changes to keep in up to date with the main develop branch before you create a Pull Request. This will help you avoid merge conflicts when raising your Pull Request.
To ensure commit messages are readable when going through project history, we use a common commit message format. The message format by Angular is very comprehensive and we find it useful to follow.
Each commit message consists of a header, a body and a footer. The header is mandatory with the body and the footer as optional given the size of the commit. The header has a special format that includes a type, a scope, and a subject, where the scope of the header is optional.
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Please refer to the Angular guidelines for more details on the format.
Once you have pushed code and your branch to Github, you can open a Pull Request. There are two types of Pull Requests: Draft and Ready for review. Feel free to create a draft Pull Request for larger features that require additional input from other contributors or is a research/proof of concept task.
Here are some guidelines for making Pull Requests:
- All developers MUST submit Pull Requests for any change made on any of the Hikaya Repositories.
- The PR must be reviewed by at least two developers other than the author.
- PR Checkpoints:
- All set checks passes (We will set the checks for each individual project).
- The bug/feature/enhancement in question is fully addressed
- PRs must follow the predefined template. In the PR body, the following questions should be addressed (This is predefined when creating a new PR):
- Descriptive Title: Add the issue number followed by a brief description of the ticket e.g.,
ACT-001: Adds project status
- Descriptive Title: Add the issue number followed by a brief description of the ticket e.g.,
- What is the purpose of the PR?
- Approach used to address the issue
- Any prerequisites before/after merging?
- Review requests
- Affected Issue(s)
- Check that the application still functions as before
We are currently using a mix of GitHub Actions and Travis CI for simple build checks and deployments to our environments. We use CodeCov to provide reports on test coverage for each Pull Request against the main branches. Over time, our aim is to increase test coverage including unit tests, integration tests, end-to-end tests, and automatic deployments to development process.
We have a CI/CD process set up for deployment to all our environments. On develop, any PR that is merged will automatically deploy to our dev environment. Any developer is allowed to deploy their changes to develop environment. To request access, contact one of the maintainers.
- All folder names should only contain lowercase characters.
- All file names should have only lowercase characters and spaces should be substituted with underscores.
We'll continue updating this section as our product matures and more standards are established. We welcome any new suggestions!
Django views
- Views should be implemented using class-based views instead of function-based views.
Unit tests
- We encourage all developers to build unit tests when adding new functionality.
Linting
- Code submitted in a PR should be free of linting issues and adhere to
PEP8standards. - The project uses
Flake8for python code linting.