Our project development process is characterized by agility, collaboration, and, most importantly, respect. We firmly believe in harnessing the collective ingenuity of our team, recognizing that each individual contributes invaluable insights to our codebase, our development process is completely managed on Github, using Github based projects.
Home
repo serves a special role in the organization, it's the starting point of all development.
- It links to all products & components
- Put only stories, identified with tag
type_story
in the home repo
To streamline our development workflow, we have adopted the GitHub-style projects framework, with all repositories linked to the ThreeFold Grid (tfgrid) product (e.g., version 3.6.0).
- Various views, such as StoryCards for a high-level overview, repository-specific views, and prioritized views, enhance project visibility.
- All repositories are managed within a centralized project, ensuring unified control and coordination.
- Milestones, aligned with semantic versioning, serve as a means to categorize and organize issues, providing versioning per component.
- Each product is clearly outlined in a dedicated project section within the "home" repository.
- The home page in the home repository serves as a hub linking to individual product pages.
- Products are associated with relevant components slated for the upcoming release.
- Product release milestones are clearly marked on the product page.
- Release notes, accessible through each product, offer a historical overview with links to specific components used in each release.
- Interlinked relationships between products and components, as well as links to third-party products with specified version numbers, provide comprehensive tracking.
- Components are meticulously monitored within the same product project.
- A commitment to semantic versioning is mandated for all components.
When creating a new project, please use the grid template project
No Status
- Stakeholder or project owner suggests a feature/story/bug to be resolved in this release
Accepted
- The project owner accepts the item, the issue will be worked on and he commits to solve within the release
- Once accepted = then escalation is needed if it can not be done in time
In progress
- The issue is being worked on
Blocked
- We are using the Kanban way of thinking - something in this swimlane needs to be resolved asap, can be e.g. a question
- Means issue cannot be completed, attention from e.g. stakeholders is needed
Verification
- Work is being verified
- The team delivered the feature/bug/story
- Stakeholders need to agree that the issue has been resolved appropriately
- Project owner can never go from 'Verification' to 'Done' without approval from stakeholders (often represented by QA team)
- If the issue hasn't been resolved, it should go back to 'Accepted'
Done
- Everyone agreed (project owner and stakeholders) agreed that the issue was done ok
Some projects require special columns like the following
Pending Review
: Work is done, waiting for review; no need for daily progress updates.Pending Deployment
: If deployment is needed for QA testing on the staging instance.
Creating a repository involves establishing a foundation for collaborative development. Follow these guidelines to ensure consistency and best practices in repository creation.
- Choose a clear and descriptive name for the repository.
- Use lowercase letters and hyphens for improved readability.
- Include a comprehensive README.md file.
- Provide essential information about the project, including setup instructions, dependencies, and usage guidelines.
- Include a LICENSE file specifying the project's licensing terms, threefoldtech is using Apache2 License.
- Use github templates to provide proper template for issues bug_report or feature request
- Use github templates to provide proper template for pull requests
- Set up a continuous integration (CI) pipeline using a tool like GitHub Actions.
- Include linting, tests and code quality checks in the CI process.
- Set up automation to deployment on staging, and production server
- Building docker images
- Building flists
- Pushing to the hub
- Publishing packages
Consider the following for Effective Issue Reporting
-
Title:
- Provide a clear and concise title that summarizes the issue.
-
Description:
- Offer a detailed description of the issue, including what you expected to happen and what actually occurred.
- Provide steps to reproduce the issue, if possible.
- Include any error messages received.
-
Environment:
- Specify the environment in which the issue occurred (e.g., operating system, browser, version).
-
Attachments:
- Attach relevant files or screenshots to help visualize the problem.
-
Issue Type:
- Label the issue with an appropriate type (e.g., bug, feature request, question).
-
Priority:
- If applicable, assign a priority level to indicate the urgency of the issue.
-
Version Information:
- Include information about the version of the software or application where the issue was encountered.
-
Labels:
- Apply relevant labels to categorize the issue (e.g., priority levels, type of issue).
-
Reproducibility:
- Clearly state whether the issue is reproducible and under what conditions.
-
Additional Context:
- Provide any additional context that might help in understanding and addressing the issue.
-
Assigned:
- If known, assign the issue to the responsible team member or developer.
-
Discussion:
- Engage in discussions with the development team and other stakeholders to gather insights and potential solutions.
By following these guidelines, you contribute to a more efficient issue resolution process, enabling developers and the team to address concerns promptly and effectively.
See issue labels
Each issue has the name of a branch in the title as [development_something], the name 'development' can be skipped and its the default or previous could also be written as [something] but don't forget branch is development_... If not specified, it is to be fixed/developed on development.
We use milestones for version numbers e.g 1.4.2
means this issue is going to be part of the release of 1.4.2
of the component.
It's very important that nobody works on any issue in milestones not part of the global project plan
- No milestone means need to be sorted
- Number e.g
1.4.2
means
So issues with no milestones can only be in 1 condition: new and not sorted out yet where (repo) it belongs
We encourage collaborative branching. Meaning any group of people working within the same scope are highly encouraged to work on the same branch, trusting and communicating with one another.
Our branching strategy is:
master
is the last stable releasemaster_$hotfix
is only for solving BLOCKING issues which are in the field on the last release- short living
development
is where all stories branch from, and the one that has hotfixes if neededdevelopment_$storyname
- branch for a story
- always updated from development(_hotfixes)
development_$storyname_$reviewname
- short living branch for when reviews are needed for a story
development_hotfixes
short living hotfix(es) to allow people to review and then put on development- now everyone should update from or development or development_hotfixes
- development_hotfixes is always newer than development
integration
is a branch used to integrate development branches- never develop on it, its for verifying & doing tests
We have branches for new features/disruptive changes. These have a prefix of development_<relevantname>
Each project and story should define which branches to use & the branching strategy.
There should never be any branch on the system which can not be found back by looking at the stories in the home
repo.
Title of the story : in between []
When developers or a group initiate work on a separate branch and seek input from their peers, it is recommended to promptly open a draft pull request
for seamless communication. Upon completion of the work, opening a pull request signals that the work is:
- Complete as Defined in the Project: The work aligns with the predefined goals and specifications outlined in the project.
- Well Tested: Thorough testing has been conducted to ensure the reliability and functionality of the code.
- Well Documented: Comprehensive documentation accompanies the code, aiding in understanding and future maintenance.
When creating pull requests (PRs), adhere to the following best practices for effective collaboration:
- Early Draft PRs: Open a draft pull request as soon as work begins on a different branch. This allows for ongoing communication and collaboration with peers throughout the development process.
- Timely Updates: Regularly update the PR as new changes are made to keep reviewers informed of progress.
- Clear and Concise Title: Use a clear and concise title that summarizes the purpose or goal of the pull request.
- Detailed Description: Provide a comprehensive description of the changes made, the problem solved, and any relevant context. This aids reviewers in understanding the purpose and impact of the changes.
- Link to Issues: If the pull request addresses specific issues, link them to provide additional context and traceability.
- Reviewers and Assignees: Assign the appropriate reviewers and, if applicable, assignees to ensure that the right people are involved in the review process.
- Complete Work: Ensure that the work is complete as defined in the project requirements. Address any outstanding issues before marking the PR as ready for review.
- Thorough Testing: Verify that the code has undergone thorough testing. Include details about the testing strategy and results in the PR description.
- Documentation: Confirm that the changes are well-documented. Documentation should not only explain how the code works but also guide future developers on its usage and maintenance.
- Provide constructive feedback and suggestions for improvement.
- Address Feedback: Be responsive to feedback from reviewers. Address comments and concerns promptly to facilitate a smooth review process.
- Code Style and Standards: Ensure that the code follows established style guidelines and coding standards. Consistent formatting contributes to maintainability.
- Status Checks: Ensure that automated status checks, such as continuous integration (CI) tests, pass successfully before merging.
- The Author should be the one merging the Pull Request, given their responsibility to keep their issues updated as well.
By adhering to these best practices, you contribute to a collaborative and efficient development process, fostering a culture of high-quality code and effective communication within the team.
Clear and informative commit messages are essential for understanding the history of a project. Follow these guidelines to create meaningful commit messages.
- Start with a concise one-line summary
- Use present-tense verbs (e.g., "Add," "Fix," "Update") to describe the action.
- Optionally, provide a more detailed explanation.
- Break long explanations into bullet points if needed.
- Clearly describe the purpose of the commit.
- Include information about why the change is necessary.
- If the commit is related to an issue, reference it in the message.
- Use keywords like "Fixes," "Closes," or "Resolves."
- Be consistent with your writing style and formatting.
- Use the imperative mood consistently throughout.
Here's a good example of a commit message
Add user authentication feature
- Implement user login functionality
- Enhance user registration form
- Fixes #123
Changes
- Bug fix
- Update
- Important changes
If you're the sole developer on the branch, you can use rebase, if more people are collaborating together, use merge
Squash only when it makes the history cleaner. Feature branch is a good example, because it is often short-lived, small, and authored by 1 developer.
On the other hand, use regular merge for big feature co-authored by multiple developers eg. long-lived branches, please be aware of the Disadvantages of squash merges
Before tagging a release, open a branch named with the intended version e.g 10.5.x with the quality level - alpha: doesn't have all the features, but you can use the features in there - beta: no major, or blocking bugs. All features working for the customer as promised, no blocking bugs - production: no major, no blocking, no minor bugs and the documentation is ready
check the release process document for more information
Issues categorized as blockers include:
- Inability of the customer to access the functionality as described in the manual.
- Stability concerns that impede progress, particularly instances where the system crashes.
- Security issues that act as barriers to further development.
- Stability issues that hinder smooth operation.
- Performance concerns labeled as blockers when they prevent continuation.
- Performance issues classified as major when they allow for continued work.
In teams operating remotely, complete transparency is of utmost importance.
Visibility into development progress is crucial and is best achieved through the use of storycards and issues.
To facilitate clear communication, commenting daily is a critical aspect of our process. We advocate for the following format, which aids in asynchronous communication:
## Work Completed:
Summarize the tasks successfully finished in relation to the issue. Provide specific details to ensure clarity.
## Work in Progress (WIP):
Detail ongoing efforts and remaining tasks related to this issue. Clearly outline items currently being worked on and those still needing attention.
## Investigation and Solution:
If no work has been completed or is in progress, elaborate on the investigative work undertaken to address the issue. Provide insights into the problem, and if a solution was reached, include it.
For issues or stories labeled with priority_critical
, continuous updates should be at least two updates per day to keep stakeholders informed.
Including an Estimated Time of Arrival (ETA) in the comments is essential. While it serves as an estimation subject to change with new findings, it provides a valuable projection of completion.
QA plays a crucial role in delivering high-quality software. This document outlines responsibilities, expectations, and best practices.
- Attend daily standups for progress updates, issue discussions, and coordination.
- Collaborate on test plans for each sprint.
- Execute test plans manually and through automated testing.
- Log and prioritize defects.
- Track nightly tests.
- Maintain updated test documentation.
- Verify issues and user stories before closure.
- Conduct test runs across different environments.
- Conduct BAM sessions twice weekly to address community feedback, covering both
test_feedback
repository and active projects.
- Expand responsibilities to include various testing types such as:
- Performance testing
- Security testing
- Compatibility testing
- Usability testing
- Regression testing
- Lead the creation of detailed test plans.
- Define a testing strategy, emphasizing automation.
- Review and close issues, ensuring alignment with the test plan.
- Facilitate communication between QA and development teams.
- Provide a comprehensive test plan, authored exclusively by the QA lead that serves as the source of truth for the verification process
- Verify stories in a two-step process
- As soon as the story is moved to In Verification column, QA team can pickup the issue, they need to log their scenarios, executions and link to the testcase in the testplan.
- QA lead can then verify it's aligned to the original requirements and it was properly verified before closing
- QA leads need to test the main features by themselves.
- Automate regression testing through github workflows, and any other means needed.