The workflow that we are following has been evolved to this form based on our earlier experiences with clients and our own internal projects. The individual project workflows may differ based on circumstances like client requirements, however the workflow that is explained here is the lightest form of how we do our jobs. Agility and Fail Fast are the key concepts that we try to achieve with every project.
The test strategy and policy of the company can be seen below with the test glossary. Test policy shows a high-level test approach. The test strategy contains more details about the subjects mentioned in the test policy. Both of them are applied in all projects among the company. Apart from them, explanations of terms and expansions of abbreviations in those documents can be found in the test glossary. Those documents show what we understand from Software Testing and how we apply it in BISS.
This document covers the testing and approval steps of the development activities including new features and bug-fixes.
Software testing is an activity to investigate software under test in order to provide quality-related information to stakeholders. QA (quality assurance) is the implementation of policies and procedures intended to prevent defects from reaching customers. The test team applies testing and QA activities.
Carries out the application and process development of issues opened by business units or client.
QA process includes the following test activities;
Story/Requirement Review and Analysis: User stories or requirements which are defined by the customer or product owner should be tested (static test) by the test team. Logical mistakes, gaps should be reported.
Unit Testing: Usually performed by the development team unless there is a certain necessity for the test team. The purpose is to validate that each unit of the software code performs as expected.
Exploratory Testing: It is a testing activity where test cases are not created in advance but testers check the system on the fly.
Feature Validation Tests: Testing the implementation of the user story, requirement or etc.
Smoke Testing: It is preliminary testing to reveal simple failures severe enough to reject a prospective software release.
Performance, Load, Stress, Accessibility Tests: Non-functional tests
Integration Testing, System Testing, E2E Testing: Functional tests
Change Based Testing: Regression Testing is the process of testing a system (or part of a system) that has already been tested by using a set of predefined test scripts in order to discover new errors as a result of the recent changes. The effects of software errors or regressions (low performance), functional and non-functional improvements, patches made to some areas of the system, and configuration changes can be monitored with regression testing. Retest is also performed after every bug-fix.
User Acceptance Testing (UAT) UAT should be performed by a random tester at the end of every project to increase quality if the customer or the product owner will not or cannot run it. These tests should be focused on UX. The tester should have the end-user point of view. It should be very brief because the main aim is not to find all bugs. Ideally, UAT should be performed by the customer.
Other activities;
This process is called Software Test Life Cycle (STLC) in international standards. It is carried out in parallel with the Software Development Life Cycle (SDLC) process for BISS.
The STLC process starts with the submission of the test request and the inclusion of the test team in the project as part of the system analysis studies. This process is continued and completed with Requirements Review, Design & Development, Feature Approvement, and Live Control.
Well-written requirements form the foundation of a successful project. The requirements review is an opportunity to check the requirements document for errors and omissions, and confirm that the overall quality of the requirements is acceptable before the project proceeds. It is also one final opportunity to communicate and confirm project requirements with all stakeholders. The test team carefully reviews all requirements.
Meanwhile, test plan preparation shall be started if requirements are clarified. According to the requirements, technologies to be used, test approach, test strategy, test types to be performed in each test level should be documented. Also, test entry and exit criteria should be defined. This document (test plan) shall not contain technical details which could be changed during the project. It shall be approved by the product owner and be read by all the stakeholders.
In the design and development phase, test scenarios are prepared and the prepared scenarios are reviewed by stakeholders if possible. At the same time, test data is prepared in order to run test scenarios.
Test environment preparation steps are started to be executed after test data is prepared. In this step, the environment in which the prepared test scenarios can be realized and the necessary tools are set up and adjusted. If test scenarios are automated, automatic test scripts shall be prepared in this step.
After test data and the test environment are prepared, functional testing and non-functional testing activities shall be performed.
Automated tests consist of scenarios prepared during the creation of automatic scripts and automated regression scenarios. Manual tests are based on testing the prepared scenarios like the end-user. Both are applied in order to provide optimum efficiency in the STLC process.
The smoke test is also carried out by the Test Team. This type of test is carried out in order to control the main functions of a product after deployment to any environment (test, production, etc.).
UAT tests should be performed by a test team member except project’s testers if it is not performed by the customer or the product owner.
All other non-functional tests like performance, load, stress or accessibility testing could be performed if needed in the project.
Error records are created in the Project Management Tool for detected defects. Resolved defects are tested if the entry criteria that is defined in the test plan is satisfied.
The test report containing the latest status of the project is prepared by the test team manually or automatically and shared with the PO, development team or all stakeholders, periodically. Its content and detail level should be decided by the development team.
Entry criteria are the required conditions and standards for work product quality that must be present or met prior to the start of a test phase. Entry criteria include the following:
Exit criteria are the required conditions and standards for work product quality that block the promotion of incomplete or defective work products to the next test phase of the component. Exit criteria include the following:
| Abrreviation | Expansion |
|---|---|
| STLC | Software Test Life Cycle |
| SDLC | Software Development Life Cycle |
| ISTQB | International Software Testing Qualifications Board |
| IEEE | Institute of Electrical and Electronics Engineers |
| Term | Explanation |
|---|---|
| Requirements traceability matrix | A document that demonstrates the relation between requirements and other artifacts |
| Static test | Tests that are run without executing the code. It consists of manual and automated reviews. |
| Dynamic test | Tests that are run while the application is running. |
| Functional test | Tests that check whether the application is working right. |
| Non-functional tests | Tests that check whether the application is the right product that meets non-functional requirements like performance, usability, and etc. |
| Change-based testing | Testing to verify the latest changes and/or their effects on the whole system. |
| White-box testing | Tests which perform with consideration of internal structure of the software. |
| Black-box testing | Tests which perform with consideration of specifications of the software. |
| Grey-box testing | Tests which perform with consideration of specifications and internal structure of the software. |
| Regression test | Testing an application that has been tested before to be sure that recent changes have not broken anything covered by the regression test suite. |
| Re-test (Confirmation Test) | Testing a part of the application that contains an untested change that has been tested before. |
| Test data | Data that was created during or before test design activities. It could be used by the test or application during test execution or implementation. |
| Test design | A process that test objectives are converted into test deliverables like plans, scenarios, data. |
| Test execution | The process contains running tests and validating actual and expected results. |
| Test implementation | A process that test scenarios are detailed (with steps and test data) and/or automated. |
| Work product | Any output in SDLC (analysis document, code, test scenario, etc.) |
| Author | Work product creator. |
| Bug/Defect | A mismatch that might cause a failure in production between the requirement and software. |
| Requirement | Definition of what customer needs. |
| User Story | Formatted requirements by using everyday or business language to explain what really user needs including non-functional requirements. It also has acceptance criteria. |
| Acceptance Criteria | The criteria that software must satisfy to be accepted by the user. |
| Test Script | Automated or manual scripts to use executing a test. |
Bosphorus Industrial Software Solutions (BISS) strongly believes that testing saves cost and time, while providing efficiency and quality to all software products. The main idea is to deliver the product in such a quality that the users will have the intended experience.
BISS defines Testing as validation and quality improvement of the product from ideation phase to the final delivery within all angles. Testing is an ongoing process together with other processes in SDLC.
The testing approach is determined according to the project requirements, customer expectations, team knowledge, and project duration. More than one approach might be combined to perform tests in the project.
Our process follows the IEEE and ISTQB standards.
This process applies as a general rule for all the projects at BISS. To see the equivalent steps in the STLC or SDLC of each activity please refer to the Test Strategy Document.
This process can be started along with phase 3.
Preparation of the test closure document which includes;
In each step, there are entry and exit criteria that need to be met. These criteria usually vary from project to project but the common entry and exit criteria can be found in the Test Strategy Document.
| Test Level | Owner | Test Types | Objective(s) |
|---|---|---|---|
| Unit(Component) |
|
|
|
| Integration |
|
|
|
| System | Software Tester |
|
|
| Acceptance |
|
|
To be sure the software is able to do required tasks in the real world. |
From “Requirement Management” to the actual “Product to be Deployed” the process that we follow as a company can be seen below.
This process flow also helps us to add any CR (Change request) during development since the teams are already changing their architectural and software design during the implementation phase. The thing that we are trying to achieve is failing fast so that we can adapt to any circumstance, like environment limitations, or CRs.
The part that has been marked as the “Agile” is the part that we focus as development team and use the Agile Frameworks (Scrum or Kanban) to track our development. This part can be extended as follows:
This way of working helps us to work closely with stakeholders and adapt to any request from them immediately.
The process that we follow for each sprint is shown below, this also shapes our scrum board for sprints as well. Each box represents a column on scrum board while to move an issue from one box to another requires the “Quality Gateway” between those boxes to be met.
Each stage here represent a column on a team’s scrum board. These can differ based on client or team needs. It can also change based on the project type itself, yet, this creates a good basis in order to follow a common way of working.
In order to help each member of the team, we have some “Quality Gateways” that we highly suggests teams to use in order to increase the product quality as well as saving teams time for not going back and forth between the stages.
Quality Gateway 1: The first “Quality Gateway” is there in order to help developers understand everything about the issue. There are things to be taken into consideration before taking any issue to the next sprint, and they represent this QG.
Quality Gateway 2: This gateway is really similar to the QG1 where all the things that were mentioned there should be reconsidered. Other than those we recommend:
Quality Gateway 3: This part is supported with the CI pipelines for achieving the quality, yet, it still needs some investigation by the team itself.
Quality Gateway 4: This gateway decides if the feature should be in the next increment. Here PO and QA testers checks the issues and sees if it satisfies the requirements.
Unless there is strict request from client, we highly encourage our teams to use “Agile” as their software development process. However, there can be projects where all the things are already planned, all the deliverables are time boxed and decided beforehand and when there is a priority on delivering a finished product instead of failing fast, instead of calling our methodologies “Scrum, but…” we can decide on working with different processes for software development.
To achieve the agility in our projects, we leverage the Scrum framework. The best traits that we see in scrum are being lightweight and simple to understand. It is true that Scrum is hard to master, however, since we adopted it from the day we started the company, we are highly motivated about using it to our benefit. Please spend a bit of time to go over the Scrum Guide for more detailed information on Scrum.
This event ends up producing the artifacts that can be seen below:
There are two concepts that we apply in scrum in order to achieve transparency during the scrum and within artifacts.
Acceptance Criteria can be used to leverage those two concepts.
At this point it is should be clear that all the things mentioned above are the things that we require from our project teams to apply to their projects. However, the time limits, number of project members are based on different requirements such as:
The requirement levels diagram below summarizes what are the responsibilities for each entity as well as where the requirements fall under scrum.
Frequency: Once per sprint
Meeting length: 2 - 8 hours
Agile planning is focused on getting the answers to simple questions like
The project managers also explore hidden dependencies for various activities to minimize the idle time and optimize delivery period. Agile planning revolves around measuring the velocity and efficiency of an Agile team to assess when it can turn the user stories into processes, production-ready software, and quality product delivery. The ultimate goal of Agile planning is to have a clear picture of project vision, production roadmap with sprint schedule, and business interests. To simplify the things, Agile planning can be stipulated of different levels;
Agile planning starts with product vision creation ensuring that strategies are aligned properly and the development team spends its time on creating the right valuable product. The product vision guides the team members for the shared goal like a lighthouse. The product vision statement tells about ‘how the product supports organization’s strategies.’ You can simplify the process of Agile product vision development by making it a four-step exercise – development, drafting, validation, finalizing. The following five tips will help you to get the most out of it:
An Agile product roadmap is a plan that describes the way the product is likely to grow; it also facilitates for learning to change. To succeed in Agile management, you need to have a goal-oriented roadmap as it provides crucial information about everyday work by the team. As a powerful Agile management tool, it helps to align all the stakeholders and to estimate sufficient budget for quality product development as per schedule. Creating effective roadmap is often a challenge because changes occur unexpectedly in an Agile environment; however, the following five tips will help you plan the most effective roadmap:
In Agile landscape, the release is a set of product increments released to the customer. The release plan defines how much work your team will deliver by the mentioned deadline. Release planning is the collaborative task involving Scrum master (facilitates the meeting), Product owner (shares product backlog view), Agile team (provides insights into technical dependencies & feasibility) and Stakeholders (the trusted advisors). The following five tips will help you in effective release planning:
The iteration planning is done by holding a meeting, where all the team members determine the volume of backlog items they can commit to deliver during the next iteration. The commitment is made according to the team’s velocity and iteration schedule. The following five tips will help you in effective iteration planning:
Like many other planning activities for Agile management, the daily commitment planning also needs the synchronized partnership of teams. The daily planning meeting is focused on completing the top-priority features. The 15-minute standup meeting facilitates face-to-face communication on individual’s progress and impediments if any. The following five tips will help you in progress-oriented daily commitment planning:
Frequency: Daily
Meeting length: 10 - 15 minutes
Scrum meetings are a part of agile meetings, or scrum ceremonies, where all team members can sync up on the work they did in the last 24 hours, and go over what’s on deck for the next 24 hours.
Is there anything preventing contributors from getting work done? Things to bring up here might be technical limitations, departmental and team dependencies, and personal limitations (like vacations booked, people out sick, etc.).
This is a quick rundown of what got done yesterday (and if anything didn’t get done, then why). This isn’t the time for each person to run down their whole to-do list – they should focus on the large chunks of work that made up their deep focus time, and the activities that are relevant to your team as a whole.
Here, each team member will say what they want to accomplish – in other words, what they can be held accountable for in tomorrow’s daily scrum meeting.
This agenda item will help the scrum master get an idea of how the team is feeling about how their day-to-day activities are impacting overall goals for the team, and how contributors are feeling about the pace of the sprint.
Being late for any meeting is disruptive, but it’s particularly distracting when the meetings are only 10 minutes long. Hold your team accountable for being on time, every time.
Giving each team member the opportunity to talk is hugely important. Reinforce this at the start of each scrum if you find that certain team members have a tendency to ramble on.
Don’t over-complicate your scrum meetings. Keep the agenda the same each time you meet, and make the technology for meeting consistent. Daily scrum meetings involve less than 10 minutes of meeting prep, max.
Referenced from here.
Frequency: Once per sprint
Meeting length: 1 - 4 hours
Many of those practicing Scrum mistakenly call the Sprint Review a Demo. Is it just a matter of terminology? From my point of view, the Sprint Review is the most underestimated Scrum Event, and for many companies, its potential is yet to be revealed. It is true that the Demonstration or Demo is an essential part of the Sprint Review, but it isn’t the only one.
The Sprint Review is much more than just a Demo.
Let’s find out why.
The Scrum Team and stakeholders (users, other teams, managers, investors, sponsors, customers, etc.) One could say that we invite the whole world to the Sprint Review and this is absolutely true.
Sprint is one of the five official Scrum Events and is an opportunity for the Scrum Team to practice empiricism. Here is a short summary of what we inspect and adapt during the Sprint Review.
Inspect: Sprint, Product Backlog, Increment, Marketplace, Budget, Timeline, Capabilities.
Adapt: Product Backlog, Release Plan.
The Sprint Review is not just about product demonstration, it is an inspection of the completed Sprint, the Product Backlog and the marketplace. Also, it is a place for reviewing budgets, timeline and capabilities. Each Sprint is an important risk mitigation tool and the Sprint Review is a decision point for the Product Owner.
Each Sprint can be the last one. The Product Owner makes a formal decision regarding financing the next Sprint during the Sprint Review.
Here are some decisions that can be formally made:
Scrum is based on iterative and incremental development principles, which means getting feedback and making continuous updates to the Product Backlog. Unfortunately, teams often forget about it.
The Sprint Review is a great tool for getting feedback, while the number of changes to the Product Backlog after the Sprint Review can be an important indicator of how healthy your Scrum is.
Many teams/companies underutilize the entrepreneurial spirit of Scrum and its concept where the Product Owner is a mini-CEO of the Product. Very often, stakeholders attend only the Increment demonstration (usually done using a projector) with few questions asked and then everybody leaves shortly afterwards. This may happen for several reasons:
Well, I wrote quite a lot. Let’s sum it up.
Frequency: Once or twice per sprint (Not mandatory)
Meeting length: 1 - 4 hours
Sprint Retrospective is an opportunity for the Scrum Team to inspect itself and create a plan for improvements to be enacted during the next Sprint.
The Sprint Retrospective occurs after the Sprint Review and prior to the next Sprint Planning. This is at most a three-hour meeting for one-month Sprints. For shorter Sprints, the event is usually shorter. The Scrum Master ensures that the event takes place and that attendants understand its purpose. This is the opportunity for the Scrum Team to improve and all member should be in attendance.
The team discusses:
The Scrum Master encourages the Scrum Team to improve its development process and practices to make it more effective and enjoyable for the next Sprint. During each Sprint Retrospective, the Scrum Team plans ways to increase product quality by improving work processes or adapting the definition of “Done” if appropriate and not in conflict with product or organizational standards.
By the end of the Sprint Retrospective, the Scrum Team should have identified improvements that it will implement in the next Sprint. Implementing these improvements in the next Sprint is the adaptation to the inspection of the Scrum Team itself. Although improvements may be implemented at any time, the Sprint Retrospective provides a formal opportunity to focus on inspection and adaptation.
Frequency: Once or twice per sprint (Not mandatory)
Meeting length: 2 - 4 hours
Backlog refinement (formerly known as backlog grooming) is when the product owner and some, or all, of the rest of the team review items on the backlog to ensure the backlog contains the appropriate items, that they are prioritized, and that the items at the top of the backlog are ready for delivery.
Items should be discussed and prioritized based on customer / market needs.
The issues should be completed within a sprint, thus, if there are any issues that are not
Some of the issues may be deferred due to change of requirements or necessity of that feature, thus, cleanup of the backlog items can be done here.
This has its’ own meeting, attendees should not discuss the sprints that these items will be developed.
This meeting is to clean the backlog, completed items are not in scope of this meetings.
These can be done during retrospective, this has nothing to do with the grooming meetings.
Frequency: Daily
Duration: 1 - 4 weeks
The heart of Scrum is a Sprint, a time-box of one month or less during which a “Done”, useable, and potentially releasable product Increment is created. Sprints have consistent durations throughout a development effort. A new Sprint starts immediately after the conclusion of the previous Sprint.
Sprints contain and consist of the Sprint Planning, Daily Scrums, the development work, the Sprint Review, and the Sprint Retrospective.
No changes are made that would endanger the Sprint Goal; Quality goals do not decrease; and, Scope may be clarified and re-negotiated between the Product Owner and Development Team as more is learned. Each Sprint may be considered a project with no more than a one-month horizon. Like projects, Sprints are used to accomplish something. Each Sprint has a goal of what is to be built, a design and flexible plan that will guide building it, the work, and the resultant product increment.
Sprints are limited to one calendar month. When a Sprint’s horizon is too long the definition of what is being built may change, complexity may rise, and risk may increase. Sprints enable predictability by ensuring inspection and adaptation of progress toward a Sprint Goal at least every calendar month. Sprints also limit risk to one calendar month of cost.
A Sprint can be cancelled before the Sprint time-box is over. Only the Product Owner has the authority to cancel the Sprint, although he or she may do so under influence from the stakeholders, the Development Team, or the Scrum Master.
A Sprint would be cancelled if the Sprint Goal becomes obsolete. This might occur if the company changes direction or if market or technology conditions change. In general, a Sprint should be cancelled if it no longer makes sense given the circumstances. But, due to the short duration of Sprints, cancellation rarely makes sense.
When a Sprint is cancelled, any completed and “Done” Product Backlog items are reviewed. If part of the work is potentially releasable, the Product Owner typically accepts it. All incomplete Product Backlog Items are re-estimated and put back on the Product Backlog. The work done on them depreciates quickly and must be frequently re-estimated.
Sprint cancellations consume resources, since everyone regroups in another Sprint Planning to start another Sprint. Sprint cancellations are often traumatic to the Scrum Team, and are very uncommon.
Definition of Ready is the properties required for a task to be started. It has to be clear, open and transparent.
User story has to cover all necessary items which are based on INVEST principles.
Invest principles items;
Accept an user story is ready, below items have to covered by the user story;
- The conditions of satisfaction have been fully identified for the story.
- The story details have to be understandable by the all scrum team.
- The story has been estimated and is under a certain size which is defined by the scrum team.
- The team’s user interface designer or Product Owner has mocked up, or even fully designed, any screens affected by the story.
- All external dependencies have been resolved, whether the dependency was on another team or on an outside vendor.
- Test environment or devices which is related the story, have to be ready.
- Prioritized sprint backlog
- Defects, user stories and other work the team has committed to are contained in the sprint backlog
- No hidden work, all backlog items have to be detailed enough for next sprint.
- All team members have calculated their individual capacity for the sprint
- All users stories meet the definition of Ready.
Implementation or Work Item;
- Has to be delivered as an increment.
- Has to cover all definition of done rules.
Test environment have to be ready for related item.
Definition of Ready may not be covered all items which ared listed above. Project members have to select necessary items for their and customer needs. The items can be extended and teams can add their own custom rules to team’s definition of ready list. The most important rule is, each team member has to be beware of the definition of ready and follow the rules.
The Definition of Done is an agreed upon set of items that must be completed before a project, user story, test case, deployment steps etc. can be considered complete. It is applied consistently and serves as an official gate separating things from being “in progress” to “done.”
- Code have to be written by following defined code formatting.
- Comments have to be added to explain complex solutions.
- Implementation have to be complete within defined code complexity levels
- Any other third party solution(Library, Framework etc.) which endangers CDP, should not be used in implementation.
- Before committing implementation, written code/solution have to be reviewed by at least other one developer.
- If implementation needs integration with another module and the module has not implemented during implementation, mock data or mock module should be used to test implementation.
- Unit tests have to be written by developer.
- All edge cases have to be tested by the developers.
- If it is needed, to keep CI/CD pipeline alive, necessary updates have to be done on CI/CD configuration for tests.
- Implementation has to be tested by the testers before deployment.
- Before deployment, tester has to complete all regression tests to be sure that implementation is not effects any other modules.
- Before deployment, all automated tests have to be run. If test coverage below defined coverage percentage, implementation have to be rolled back.
- If implementation uses third party solutions/app, the packages should be added for deployment environment(Docker or Yocto scripts)
Definition of Done may not be covered all items which is listed above. Project members have to select necessary items for their and customer needs. The items can be extended and teams can add their own custom rules to team’s definition of done list. The most important rule is, each team member has to be beware of the definition of done and follow the rules.
Acceptance criteria are the conditions that a software product must meet to be accepted by a user, a customer, or other system. They are unique for each user story and define the feature behavior from the end-user’s perspective. Well-written acceptance criteria help avoid unexpected results in the end of a development stage and ensure that all stakeholders and users are satisfied with what they get.
Main purposes of the Acceptance Criteria is clarifying the stakeholder’s requirements.
Some of the criteria are defined and written by the product owner when he or she creates the product backlog. And the others can be further specified by the team during user stories discussions after sprint planning.
Acceptance Criteria have to be written before development starts.
Acceptance Criteria shouldn’t be too narrow.
Acceptance Criteria have to be achievable in one sprint iteration.
Acceptance Criteria have to be measurable and not too broad.
Acceptance Criteria shouldn’t contain Technical Details
Acceptance Criteria have to be understandable by all Scrum Team members
Acceptance Criteria have to be testable
Acceptance Criteria should contain;
Feature scope detalization
Acceptance Criteria define the boundaries of user stories. They provide precise details on functionality that help the team understand whether the story is completed and works as expected.
Describing negative scenarios
Acceptance Criteria may require the system to recognize unsafe password inputs and prevent a user from proceeding further. Invalid password format is an example of a so-called negative scenario when a user does invalid inputs or behaves unexpectedly. Acceptance Criteria define these scenarios and explain how the system must react on them.
Setting communication
Acceptance criteria synchronize the visions of the client and the development team. They ensure that everyone has a common understanding of the requirements: Developers know exactly what kind of behavior the feature must demonstrate, while stakeholders and the client understand what’s expected from the feature.
Streamlining acceptance testing
Acceptance criteria are the basis of the user story acceptance testing. Each acceptance criterion must be independently testable and thus have a clear pass or fail scenarios. They can also be used to verify the story via automated tests
Feature estimation
Acceptance criteria specify what exactly must be developed by the team. Once the team has precise requirements, they can split user stories into tasks that can be correctly estimated.
Scenario the name for the behavior that will be described
Given the beginning state of the scenario
When specific action that the user makes
Then the outcome of the action in “When”
And used to continue any of three previous statements
Example;
User story: As a user, I want to be able to recover the password to my account, so that I will be able to access my account in case I forgot the password.
Scenario: Forgot password
Given: The user has navigated to the login page
When: The user selected forgot password option
And: Entered a valid email to receive a link for password recovery
Then: The system sent the link to the entered email
Given: The user received the link via the email
When: The user navigated through the link received in the email
Then: The system enables the user to set a new password
Source: https://www.altexsoft.com/blog/business/acceptance-criteria-purposes-formats-and-best-practices/
Source control management is a key concept that enables developers work together where they can review each others code, develop new features without breaking each others implementations or doing the same work twice. git is the main SCM (source control management) tool that we use in BISS to store and share our code.
Most of the companies have their own guides and criteria for using the git based on their needs and requirements, for creating a better environment for developers and testers to work. In BISS, we have our own guides on how to use the git (with GitLab) that has been decided by the team to meet their requirements. Those guides are:
It can be seen that these guides are prepared with high flexibility in mind to serve all the different needs that might come using different technologies. They are also live guides meaning they evolve and change with new requirements and needs coming from our teams. At any given time, BISS uses these guides for source control management on their projects, thus, they form the standard and ensures the quality of our projects.
Commit messages should be self explanatory with enough detail for developers, maintainers, testers and every other member of the development team to understand what exactly has changed with each commit.
Commit type that will give first hints about commit change.
Summary is the must have and it has two parts in it. First part is the name of the module and the second part is the summary of the change.
Description is made out of several parts, it can be considered as a template of explaining, giving enough detail on the changes about:
Use the imperative mood in the summary line while writing commit messages. A properly written summary line for a commit message should be able to complete the following sentence: “This commit will …”.
Other than summary, all the parts are optional yet, it is highly encouraged to use them. Template and example can be found below:
template:
[~#+] Module Name Abbreviation(if needed): Summarize the change in less than 50 characters
What is changed (if needed):
- Explain new algorithm.
- Explain new dependencies.
Because (if needed):
- Explain the reasons you made this change
- Make a new bullet for each reason
- Each line should be under 72 characters
Remarks (if needed):
Include any additional notes, relevant links, or co-authors.(if needed)
Issue: #AZURE_ISSUE_IDexample:
[~] search: Refactor algorithm
What is changed:
- The new algorithm's worst case O(n log(n)).
- "HyperSupperDupper Sort" library is not used anymore.
Because:
- Old algorithm was not optimized.
- System tend to crash with big data.
Remarks:
Corner cases were not covered. (see # 11231)
These changes should resolve issue # 1337.
This commit removed the getFirst(), so please stop using it!
Issue: #2019
Co-authored-by: cool.guy <cool.guy@bosphorusiss.com>Check this article to read more about writing good commit messages. Another cool git commit can be found here.
Versioning helps us to create cornerstones in a project so that we can understand the project state. In this part versioning and semantic versioning will be discussed.
As the bigger our systems grow, and the more packages we integrate into our software; then releasing new package versions can start to become problematic:
Semantic versioning allows us to convey what have changed from one version to the next, that way we can create clever dependency specifications and keep developing and releasing new versions of our packages without unnecessarily being have to update all dependent packages.
Semantic versioning offers a scheme as below:
[MAJOR.MINOR.PATCH]
Version Incrementing Rules
Increment the:
Remarks
Reference: Semantic Versioning Specification
In this part we will develop a hypothetical application gradually and use semantic versioning along the way. Let’s say you’re building an application that is called network-manager. It has one initial requirement, it should return the IP address of network interface wherever it runs and that functionality should be available under /get-ip-address endpoint.
NOTE
There are several ways to communicate with the application. We can use arguments/options, listen for keyboard strokes, start a server inside and communicate via a client application. We’re not going into details but the idea is that an application one way or another presents interface to interact with the world around it and that part is called public API. It’s important to define which part of your software constitutes public API to use Semantic Versioning correctly.
After adding this functionality we can create a tag as v0.1.0 to point initial version.
If you run the application and reach for /get-ip-address endpoint, it responds as below:
{
"interface": "enp0s3",
"ip_address": "192.168.10.2/24"
}After a certain amount of time you realized that it takes too much time to respond. You find out the reason and send a bugfix. Time to pump the version. This change was backward compatible because the application still responds the same way. Also we didn’t add new functionality. So no need to bump major or minor units, just increasing patch unit will be enough. So the new version is v0.1.1
It’s time to bring new functionalities to the table ! You realized that it would be a good idea to show MAC address and it should be reachable via /get-mac-address endpoint. After developing this functionality time to check if everything works fine.
So you run the application and ask for MAC address via /get-mac-address, here is the response:
{
"interface": "enp0s3",
"mac_address": "0a:0b:0c:0x:0y:0z"
}It looks fine and we should give a new version. For now we have two different endpoints (/get-ip-address and /get-mac-address). Since we didn’t touch /get-ip-address endpoint, it still behaves as before and because we didn’t have any other than /get-ip-address, it’s okay to say this change was backward compatible. Yet this is a new feature, so we should bump minor unit. The new version is v0.2.0
Network-manager returns the first interface it reaches currently and because we only got one network interface in our workstation that was okay. But there might be more than one network interfaces where our application runs. The new goal is returning all IP and MAC addresses if applicable. After few changes, time to run basic checks in a different environment where we got two physical network interfaces:
/get-ip-address responds with:
[
{
"interface": "enp0s3",
"ip_address": "192.168.10.2/24"
},
{
"interface": "enp0s4",
"ip_address": "192.168.11.2/24"
}
]/get-mac-address responds with:
[
{
"interface": "enp0s3",
"mac_address": "0a:0b:0c:0x:0y:0z"
},
{
"interface": "enp0s4",
"mac_address": "1a:1b:1c:1x:1y:1z"
}
]Before this change endpoints were returning inside JSON objects, but now it returns JSON objects inside an array. This means consumer of the network-manager should change their code to be compatible with new version of network-manager and our change was not backward-compatible. We have to bump the major unit. The new version is v1.0.0
Branching strategy points to activites a project team should execute for integration, deployment and even delivery. In this part we will explain what we use for branching on daily basis and briefly touch on several branching strategy.
BISS Flow
This is the first workflow attempt that addresses multiple teams way of working. It’s not done by any means and should improve over time.
Let’s look at the usage of each branch:
Few more points:
Git Flow
This is the oldest approach that aims to solve integration problem. It has permanent master and develop branches and feature, release, hotfix branches that live limited amount of time. Releasing the software is the main goal and branches are created with this idea in mind. Depending on the circumstances, temporary branches might merge into master and/or develop branches.
Let’s briefly touch each branch:
It has too many braches to think of, requires mostly manual steps to manage and demands git CLI knowledge.
GitHub Flow
This is the much simpler form of git flow. Instead of losing the momentum while playing branches it puts emphasize on deploying more often. Master branch should be in such a state that is deployable at any time. Apart from a permanent master branch, there are temporary feature branches that brings new feature or bug/security fixes into being.
It can be explained as below:
Gitlab Flow
Gitlab flow is not so much different than GitHub flow in essence. It also utilizes permanent master and short-lived feature branches and offers merging feature branches back into master often. There are few points that make Gitlab flow different than git flow as well.
On top of what GitHub flow says, Gitlab flow offers few additional branches for different needs:
In order to prevent not needed merge commits, it offers rebasing when updating a branch from master, but when merging back into master branch opt for merging.
Since master branch is accepted as reliable, Gitlab flow promotes testing before merging back into master.
A Merge Request (MR) is a request to merge one branch into another.
Use merge requests to visualize and collaborate on proposed changes to source code
Before creating a merge request, read through an introduction to Merge Requests to familiarize yourself with the concept, the terminology, and to learn what you can do with them.
Every merge request starts by creating a branch. You can either do it locally through the command line, via a Git CLI application, or through the GitLab UI.
Create a branch and commit your changes
CLI Example
git checkout -b "feature_branch" // Create a local branch with checkout
You can also create a branch from Web Application, it depends on your work style. If you are creating a branch from GitLab UI and developing it from your favorite IDE; these commands will help you out:
git fetch
git checkout feature_branchAfter creating a branch you should add your changes and commit your changes with commit message. For example:
git add src/* // Add every changed file located at /src path
git commit -m "Add Login Endpoint."Push your local branch to remote
git push --set-upstream origin feature_branch // Push your local branch to remote
Now you are ready to create your merge request.
Create a Merge Request
When you start a new merge request, regardless of the method, you are taken to the New Merge Request page to fill it with information about the merge request.
Important Notes:
*Always create merge request to source branch(the branch where you created new branch from).
For example if you created a branch from 'dev',open your merge request to 'dev'. Not 'master' or any other branches.When creating merge request follow these steps listed below
Assign the merge request to a colleague for review. Generally more than one assignees are better.
Set a milestone to track time-sensitive changes.
Add labels to help contextualize and filter your merge requests over time.
Attach a related issue.
Add merge request dependencies to restrict it to be merged only when other merge requests have been merged.
Set the merge request as a Draft to avoid accidental merges before it is ready. While doing that you can use title prefix: WIP:.Don’t forget to add description line when it will be ready.
Write a description for changes (It’s also helps reviewers for understanding what are they looking at.) While writing a merge request description be sure you are helping reviewer to what he/she is looking at. Otherwise you should okay with your colleagues closing your merge request without merging it.
Description Example:
## What does this MR Do?
* Adds Session Endpoint Paths to API Path List
* Reconfigure Public, User and Techinician Role Available API Path Lists.
* Adds Login, Logout and ValidateSession Endpoints
Closes #25!(Session Implementation)WAITING INPUTS FROM “SAYIN TOP”