[ieeeSW] Improving SPB technical presentation and minor fixes

Paulo Meireles
1 parent f537aec0
Showing 1 changed file with 109 additions and 116 deletions Show diff stats
ieeeSW/releaseEng3/IEEE_ThemeIssue_ReleaseEng_CD.md
@@ -72,21 +72,21 @@ benefits [2].
  
 SPB is a governmental program created to foster sharing and collaboration on
 Open Source Software (OSS) development for the Brazilian public administration.
-In their own projects, the Ministry managed both software requirements and server
-infrastructure. However, its hierarchical and traditional processes made them
-unfamiliar with new software development techniques, such as CD. Any of our
-requests had to pass through layers of bureaucracy before being answered;
+In their own projects, the Ministry managed both software requirements and
+server infrastructure. However, its hierarchical and traditional processes made
+them unfamiliar with new software development techniques, such as CD. Any of
+our requests had to pass through layers of bureaucracy before being answered;
 accessing their infrastructure to deploy updated software was not different.
 The difficulties were aggravated because the new SPB portal is an unprecedented
 platform in the Brazilian government, with a complicated deployment process.
  
-The project suffered significant interference from the
-board of directors throughout time because the portal represents an interface between
-government and society. In light of political interests, directors continually
-imposed changes to the platform while ignoring our technical advice. In 2015,
-the board of directors was changed and, with it, the vision of the project. New
-directors had different political agendas which affected the project's
-requirements previously approved.
+The project suffered significant interference from the board of directors
+throughout time because the portal represents an interface between government
+and society. In light of political interests, directors continually imposed
+changes to the platform while ignoring our technical advice. In 2015, the board
+of directors was changed and, with it, the vision of the project. New directors
+had different political agendas which affected the project's requirements
+previously approved.
  
 <!---
 mudar em todas as ocorrências de agents por staff, mas checar com o Fabio.
@@ -96,22 +96,24 @@ In this context, we overcame two distinct challenges: (1) deconstructing
 the widespread belief among government staff that any project in partnership
 with a University is doomed to fail, and (2) dealing with bureaucracies
 involved in the deployment process.
+
 <!-- Melissa: Acho que no segundo, seria bom falar: lidar com a aritmia que as burocracias do governo causavam ao nosso processo de deploy? -->
  
 Firstly, our team was not from a typical company, consisting mainly of
-undergraduate students supported senior developers and designers, all coordinated by two professors. Accordingly, time and
-resources allocation, accountability, and team continuity might be construed
-as "unprofessional." On the government side, the SPB portal evolution was the
-first software development collaboration between universities and the Ministry
-staff involved, raising disbelief.
-
-Secondly, our team approached software deployment differently from the Ministry.
-We believed frequent delivery is better for the project’s success. In contrast,
-the Ministry is used to the idea of a single deployment at the end of the
-project, and neither their bureaucratic structure nor their technical expertise
-were conducive with this style of work. That ended up hampering the benefits of
-the tool and preventing us from showing off the fruits of the project to those
-responsible for evaluating it.
+undergraduate students supported senior developers and designers, all
+coordinated by two professors. Accordingly, time and resources allocation,
+accountability, and team continuity might be construed as "unprofessional". On
+the government side, the SPB portal evolution was the first software
+development collaboration between universities and the Ministry staff involved,
+raising disbelief.
+
+Secondly, our team approached software deployment differently from the
+Ministry.  We believed frequent delivery is better for the project’s success.
+In contrast, the Ministry is used to the idea of a single deployment at the end
+of the project, and neither their bureaucratic structure nor their technical
+expertise were conducive with this style of work. That ended up hampering the
+benefits of the tool and preventing us from showing off the fruits of the
+project to those responsible for evaluating it.
  
 <!-- Melissa: tentar dividir esse último parágrafo em 2? Tá cansativo ler ele todo - não consigo respirar :P -->
  
@@ -123,10 +125,10 @@ deploy one version of the project onto our infrastructure and showed it to the
 government evaluators. This strategy proved them we could efficiently provide
 new features, fulfill their expectations regarding the delivery of the
 requirements, and incited them to demand the latest version to be deployed in
-the Ministry infrastructure. This efficiency generated more pressure on the IT department
-responsible for the deployment routines. With each CD cycle, we gradually built
-a new relationship among all parties and, by the end of the project, we became
-active participants in the deploy operations.
+the Ministry infrastructure. This efficiency generated more pressure on the IT
+department responsible for the deployment routines. With each CD cycle, we
+gradually built a new relationship among all parties and, by the end of the
+project, we became active participants in the deploy operations.
  
 <!--
 In
@@ -137,14 +139,13 @@ team shrinked to 20 students, one designer, and two developers.
 -->
 ## Our Continuous Delivery Pipeline
  
-SPB portal is a CDE with additional social features. We built
-system-of-systems, adapting and integrating five existing OSS projects: Colab
+SPB portal is a CDE with additional social features. We built system-of-systems
+adapting and integrating five existing OSS projects: Colab
 (www.github.com/colab), Noosfero (www.noosfero.org), Gitlab (www.gitlab.com),
-Mezuro (www.mezuro.org), and Mailman (www.list.org). All integrated system
-represents a total of more than 106.253 commits and 1.347.421 lines of code.
-That solution orchestrated these multiple components and allowed us to smoothly
-provide a unified interface for final users, including single sign-on and
-global searches [1]. 
+Mezuro (www.mezuro.org), and Mailman (www.list.org).  Colab orchestrates these
+multiple components and allowed us to smoothly provide a unified interface for
+final users, including single sign-on and global searches [1]. All integrated
+system represents a total of 106.253 commits and 1.347.421 lines of code.
  
 ![The SPB Deployment Pipeline. It started when new code arrived. As the code went through each step, it was tested and improved until finally reaching the production environment. At this point, we would restart the pipeline to release new versions.](figures/pipeline_3.png)
  
@@ -154,25 +155,24 @@ practices, as presented in Figure 1.
  
 ### Automated Tests
  
-Each integrated system had to be tested with its own test suite. This checking was not
-enough, however: we even had to test the platform as a whole. Given that the
-plugins also have their own test suites and these suites assume a double role
-as both plugin tests and as integration tests. 
-If any test suite failed, by either a test error or coverage
-reduction below a certain threshold, the process stopped. Only when all tests
-passed, the pipeline proceeded to the step of release preparation.
+Each integrated system had to be tested with its own test suite. This checking
+was not enough, however: we even had to test the platform as a whole. Given
+that the plugins also have their own test suites and these suites assume a
+double role as both plugin tests and as integration tests.  If any test suite
+failed, by either a test error or coverage reduction below a certain threshold,
+the process stopped. Only when all tests passed, the pipeline proceeded to the
+step of release preparation.
  
 ### Preparing a New Release
  
 Each software component was hosted in a separate Git repository. A new release
-of a component was tagged referencing a specific new feature or bug
-fix.  SPB had its own Git repository
-(www.softwarepublico.gov.br/gitlab/softwarepublico). An SPB portal release was
-an aggregate of versions of all of its components. When a new component release
-passed all of the SPB integration tests, we manually created a corresponding
-new tag in its repository. Therefore, a new tag on any software component
-yielded a new SPB portal release. At the end of this process, we started
-packaging.
+of a component was tagged referencing a specific new feature or bug fix.  SPB
+had its own Git repository (www.softwarepublico.gov.br/gitlab/softwarepublico).
+An SPB portal release was an aggregate of versions of all of its components.
+When a new component release passed all of the SPB integration tests, we
+manually created a corresponding new tag in its repository. Therefore, a new
+tag on any software component yielded a new SPB portal release. At the end of
+this process, we started packaging.
  
 ### Packaging
  
@@ -202,19 +202,18 @@ the next step in the pipeline.
  
 ### Acceptance Tests
  
-After a new SPB portal deployment in the VE, the Ministry was
-responsible for checking the required features and bug fixes. If they
-identified a problem, they would notify the developers via
-comments on the SPB portal's issue tracker, prompting the team to fix
-it and restart the pipeline. Otherwise, we could move forward.
+After a new SPB portal deployment in the VE, the Ministry was responsible for
+checking the required features and bug fixes. If they identified a problem,
+they would notify the developers via comments on the SPB portal's issue
+tracker, prompting the team to fix it and restart the pipeline. Otherwise, we
+could move forward.
  
 ### Production Environment Deployment
  
-After the VE check, we could finally begin the
-deployment in the PE, with the same configuration management tool,
-scripts, and package versions as in the VE. After the deploy was completed,
-both VE and PE were identical. At that point, new features and bug
-fixes were finally available to end users.
+After the VE check, we could finally begin the deployment in the PE, with the
+same configuration management tool, scripts, and package versions as in the VE.
+After the deploy was completed, both VE and PE were identical. At that point,
+new features and bug fixes were finally available to end users.
  
 ## Benefits
  
@@ -227,8 +226,9 @@ project and associates them with the creation of a DevOps team.
 ![The evolution of SPB releases and the team members distribution in the period.](figures/CDReleaseAndTeamEvolution.png)
  
 In the time of 30 months, we deployed a total of 84 versions. Over 64% of these
-activities happened in the second half of 2015, with the DevOps team creation. Even with the reduction of the team as a whole, in the last months of
-the project, this pace of deployment was maintained until we finished all our
+activities happened in the second half of 2015, with the DevOps team creation.
+Even with the reduction of the team as a whole, in the last months of the
+project, this pace of deployment was maintained until we finished all our
 activities.
  
 Besides these results, working with the government, we noticed the following
@@ -236,33 +236,33 @@ additional benefits.
  
 ### Strengthening Trust in the Relationship with the Government
  
-CD helped strengthen trust in the relationship between developers and
-the Ministry staff. Before using CD, they could validate features
-developed only at the end of the release cycle, usually every four months.
-With the implementation of CD, intermediate and candidate versions became
-available, allowing them to perform small validations over time.
-Constant monitoring of the development work brought greater security to the
-Ministry leaders and improved the interactions with our team.
+CD helped strengthen trust in the relationship between developers and the
+Ministry staff. Before using CD, they could validate features developed only at
+the end of the release cycle, usually every four months.  With the
+implementation of CD, intermediate and candidate versions became available,
+allowing them to perform small validations over time.  Constant monitoring of
+the development work brought greater security to the Ministry leaders and
+improved the interactions with our team.
  
 ### Responsiveness to Change
  
 Responsiveness was one of the direct benefits of adopting the CD pipeline.
 Political interests may change requirements and priorities at any time. The
 ability to react quickly to changes requested by the Ministry was vital to the
-project’s survival for 30 months. We noticed that if we took too
-long to meet their demands, they would threaten to reduce financial support and
-even cancel the project.
+project’s survival for 30 months. We noticed that if we took too long to meet
+their demands, they would threaten to reduce financial support and even cancel
+the project.
  
 CD helped us keep the PE up-to-date, even with partial versions of a feature.
-Therefore, we always had something to show on meetings, easing their
-concerns about the final delivery of the platform. For our team, CD made
-developers more confident that the project would last a little longer.
+Therefore, we always had something to show on meetings, easing their concerns
+about the final delivery of the platform. For our team, CD made developers more
+confident that the project would last a little longer.
  
 ### Shared Responsibility
  
 According to the conventional Ministry process, the development team could not
-track what happened to the code after its delivery, since their staff was
-the only ones responsible for deployment. The implementation of CD made our
+track what happened to the code after its delivery, since their staff was the
+only ones responsible for deployment. The implementation of CD made our
 development team feel equally responsible for what was getting into production
 and take ownership of the project.
  
@@ -290,18 +290,11 @@ Fabio sugeriu Lessons Learned, mas vamos mostrar exemplos da revista para ele ol
 ## Lessons Learned
  
 Due to the successful building of the CD pipeline, we improved the Ministry
-deployment process and kept the project alive. We now look at the lessons learned.
+deployment process and kept the project alive. We now look at the lessons
+learned.
  
 ### Build CD From Scratch
  
-<!---
-We started with a team composed of 24 undergraduate students, one designer, and
-two senior developers. In 2015, our team grew to 36 students, two designers,
-eight senior developers. For 2016, due to budget constraints, our team shrinked
-to 20 students, one designer, and two developers; however, in the last 3
-months, only 6 students closed the project.
--->
-
 Taking on the responsibility for implementing CD impacted the whole team.  Most
 of our team members did not have CD know-how, and we had few working hours
 available to build the pipeline. The construction and maintenance of the CD
@@ -318,45 +311,45 @@ deployment process. The solution enabled us to automate the deployment, even
 though the process was, initially, still rudimentary.
  
 2. _Interchange team members and encourage teammates to migrate to the DevOps
-team._ The benefits were twofold: mitigating the difficulty
-in sharing knowledge between DevOps developers and feature developers, and
-evolving the process on-the-fly.
+team._ The benefits were twofold: mitigating the difficulty in sharing
+knowledge between DevOps developers and feature developers, and evolving the
+process on-the-fly.
  
 ### Overcoming Mistrust
  
 <!-- Precisa 'dessuavizar' o porque das mudanças de requisitos - a motivação para ela não era tão natural como as que ocorrem em métodos ágeis -->
 Adopting an unfamiliar approach requires trust. In the Ministry, traditionally,
 a software was the product delivered at the end of a development contract; they
-expected and were prepared to validate and deploy a single deliverable. This process
-was not adequate for the SPB: because the SPB portal is a system-of-systems,
-the steady growth of its complexity made large deliveries unsustainable. 
-Therefore, the CD approach was necessary, but how
-to build trust and gain autonomy to implement a process that was not yet part
-of the dynamics of the Ministry?
+expected and were prepared to validate and deploy a single deliverable. This
+process was not adequate for the SPB: because the SPB portal is a
+system-of-systems, the steady growth of its complexity made large deliveries
+unsustainable.  Therefore, the CD approach was necessary, but how to build
+trust and gain autonomy to implement a process that was not yet part of the
+dynamics of the Ministry?
  
 1. _Demonstrate actual results, do not simply tell._ Initially, we did not have
 access to the Ministry infrastructure, so we created our own validation
-environment.  Thus, we were able to follow the CD pipeline until
-production deployment, when we faced two problems. First, our pace of
-intermediate deliveries to the government was faster than the deployment to
-production by the Ministry staff. Second, specific issues of the Ministry
-infrastructure made some validated features not work as expected in the PE.
-That situation gave us arguments to negotiate access to the PE.
-
-2. _Make project management transparent and collaborative for government staff._
-Allowing the Ministry staff to track our development process showed them
-we were fulfilling our commitments. They started to interact more actively in
-the generation of versions and became involved in the CD. After understanding it,
-the Ministry staff helped us negotiate access to a VE with the Ministry leaders,
-creating as an isolated replica of the PE.
-
-3. _Gain the confidence of government staff._ With the PE replica, we
-were able to run the entire pipeline and win the trust of the Ministry staff
-involved in the process. They saw the mobilization and responsiveness of our
-team to generate each new version package. They also recognized the quality of our
-work and deployment process. In the end, the Ministry staff realized
-that it would be beneficial for the project if they granted us access to the
-infrastructure, both VE, and PE.
+environment.  Thus, we were able to follow the CD pipeline until production
+deployment, when we faced two problems. First, our pace of intermediate
+deliveries to the government was faster than the deployment to production by
+the Ministry staff. Second, specific issues of the Ministry infrastructure made
+some validated features not work as expected in the PE.  That situation gave us
+arguments to negotiate access to the PE.
+
+2. _Make project management transparent and collaborative for government
+staff._ Allowing the Ministry staff to track our development process showed
+them we were fulfilling our commitments. They started to interact more actively
+in the generation of versions and became involved in the CD. After
+understanding it, the Ministry staff helped us negotiate access to a VE with
+the Ministry leaders, creating as an isolated replica of the PE.
+
+3. _Gain the confidence of government staff._ With the PE replica, we were able
+to run the entire pipeline and win the trust of the Ministry staff involved in
+the process. They saw the mobilization and responsiveness of our team to
+generate each new version package. They also recognized the quality of our work
+and deployment process. In the end, the Ministry staff realized that it would
+be beneficial for the project if they granted us access to the infrastructure,
+both VE, and PE.
  
 ## References