Download as
Browse Code »

Commit ec1ea2cba7a141303faeccd1d4d81ee368eb66f6

Authored by Paulo Meireles
2 parents fadd8b51 e531f1c0
Exists in master and in 3 other branches oss_2018, oss_2018_siqueira, rework_case_study

Merge branch 'master' of http://softwarepublico.gov.br/gitlab/softwarepublico/articles

Showing 2 changed files with 135 additions and 127 deletions   Show diff stats
opensym2017/content/05-features.tex
  Diff comments   View file @ec1ea2c
1 1 \section{Features}
2 2 \label{sec:spb}
3 3  
4   -The new generation of the SPB portal combines adapted features of existing collaborative softwares
  4 +The new generation of the SPB portal combines features adapted from existing collaborative software
5 5 and features developed by the SPB team. Whenever possible, new functions
6   -(newly developed or partially modified) were sent to official repositories, as a contribution.
  6 +(newly developed or partially modified) were contributed back to the official repositories.
7 7  
8 8 As a result, we have a platform that integrates and harmonizes different features such as
9 9 social networking, mailing list, version control system, content management and
10 10 source code quality monitoring. Our aim was to develop functionalities by reusing
11   -functions of collaborative softwares already integrated to the platform. In
  11 +functionality of collaborative software already integrated to the platform. In
12 12 addition, we tried to keep this integration transparent to end users.
13 13  
14 14 \subsection{Software and Software Community}
... ... @@ -17,47 +17,47 @@ In the new SPB portal, each software has a standard set of pages and tools.
17 17 Besides accessing support pages (such as FAQ and installation guide) within the platform, users will be able to download
18 18 different versions of the software and find several mechanisms of software development management.
19 19  
20   -Focusing on the collaborative development, the Mailman was integrated to the platform in order to allow
  20 +Focusing on the collaborative development, Mailman was integrated to the platform in order to allow
21 21 the dialogue and communication between developers, users and
22 22 enthusiasts of a determined software. The software has its own mailing list whose privacy
23 23 can be configured/set by administrators.
24 24  
25   -The software has a social interface area (aka "software community") where users can find other users, blogs,
  25 +The software has a social interface area ("software community") where users can find other users, blogs,
26 26 summary of recent activities, or any other relevant community-produced content.
27 27 Users logged to the platform can request membership to different software communities
28 28 and each community member can access and edit restricted content. For this purpose,
29   -many Noosfero features related to social network and content management was integrated to the portal.
  29 +many Noosfero features related to social networking and content management were integrated to the portal.
30 30  
31 31 To assist decision-making, the new SPB has acquired assessment and statistical
32 32 tools. Now, users will be able to rate the software and make comments and all
33 33 information will be avaiable to other users. Moreover, the software has a section
34   -containing its statistical data, where values are calculated through data
  34 +containing its statistical data, where values are calculated based on data
35 35 provided by users and the system.
36 36  
37 37 The role of the administrator will be present in the software and in its community. The
38 38 administrator is responsible for moderating content, memberships and user
39   -comments. He is also the one who can make changes in the software homepage
  39 +comments. The administrator is also the one who can make changes in the software homepage
40 40 content.
41 41  
42 42 \subsection{Software Catalog and global search}
43 43  
44 44 The platform also provides a search tool called Software Catalog,
45   -which allows users to find softwares available in its directory.
  45 +which allows users to find softwares available in the portal.
46 46 In this catalog, some search options were developed to make the navigation easier,
47 47 such as filters (by type of software or category), sorting and score.
48 48  
49 49 In order to expand the searching scope and cover more types of content, the SPB team
50 50 developed the global search tool. This tool unifies search mechanisms
51   -provided by the mentioned collaborative softwares. Any user can
52   -find a public content in the context of social network, mailing list and
  51 +provided by the different collaborative software used in the SPB protal. Any user can
  52 +find a public content in the context of social networking, mailing list and
53 53 software development.
54 54  
55 55 \subsection{Software development tools}
56 56  
57 57 The new SPB also provides
58   -tools to encourage developers to keep each source code and its
59   -developments within the platform. Any created software has, by default, a
60   -related git repository with wiki pages and issues tracking. These tools are
  58 +tools to encourage developers to keep source code and its
  59 +development activity within the platform. Any created software has, by default, a
  60 +an associated git repository with wiki pages and issue tracking. These tools are
61 61 supplied by the integration of Gitlab into the platform.
62 62  
63 63 Developers can also evaluate the software source code to measure software
... ... @@ -67,7 +67,7 @@ public, which allows greater transparency between the developer and the
67 67 community that uses the software. Thereby, the maintainers can decide if the
68 68 given solution meets the source code quality requirements.
69 69  
70   -Thus, the SPB becomes a platform to stimulate the openness of the source code;
  70 +Thus, the SPB becamr a platform to stimulate the openness of the source code;
71 71 dialogue between users and the development team; and also
72 72 maintenance and evolution of the software, which will provide more
73 73 transparency in government investments.
... ...
opensym2017/content/07-process.tex
  Diff comments   View file @ec1ea2c
... ... @@ -5,19 +5,19 @@ The SPB team was composed of a variety of professionals with different levels
5 5 and skills, where most of them were undergraduate students with major in
6 6 software engineering (from 4th semester or upper). Since the students could
7 7 not dedicate many hours per week to the project, they always had the
8   -flexibility to negotiate their work schedule during the semester in order not
9   -to cause any damage to their grades. Their daily work routine in the project
10   -included programming and devops tasks.
  8 +flexibility to negotiate their work schedule during the semester in
  9 +order to not harm their classes and coursework. Their daily work routine
  10 +in the project included programming and devops tasks.
11 11  
12 12 The development of SPB project required a vast experience and background that
13   -usually undergraduate students do not have yet. For this reason, some senior
14   -developers have joined to the project to help with hard issues and to transfer
  13 +usually undergraduate students do not have yet. For this reason, a few senior
  14 +developers have joined to the project to help with the more difficult issues and to transfer
15 15 knowledge to the students. Their main task was to provide solutions for complex
16   -problems, in other words, they worked as a developer. As these professionals
  16 +problems, in other words, they worked as developers. As these professionals
17 17 are very skillful and the project could not fund a full time work for them,
18 18 some of them worked partially on the project. In addition, they lived in a
19 19 different states spread around Brazil which led much of the communication to be
20   -made via Internet.
  20 +online.
21 21  
22 22 In short, our work process was based on open and collaborative software
23 23 development practices. The development process was defined based on the
... ... @@ -26,70 +26,104 @@ high degree of automation resulting from DevOps practices. Thus, the work
26 26 process was executed in a cadenced and continuous way.
27 27  
28 28 Finally, the last group of actors of this project was composed of employees
29   -formally working for the Brazilian government, in the Ministery of Planning,
30   -Development, and Management (MP is the Brazilian acronyms). All the project
  29 +formally working for the Brazilian government, in the Ministry of Planning,
  30 +Development, and Management (MP is the Brazilian acronym). All the project
31 31 decisions, validations, and scope definitions were made by them. In this way we
32   -developed software product increments, releases, aligned with business
33   -strategic objectives. As can be seen, the project had many kinds of profiles
34   -that had to be organized and synchronized.
  32 +developed software product incrementally, with releases aligned to business
  33 +strategic objectives. As one can see, the project had many different
  34 +kinds of stakeholders that had to be organized and synchronized.
35 35  
36   -\subsection{Teams organizations}
  36 +\subsection{Team organization}
37 37  
38 38 Approximately 70\% of the development teams were composed of software
39   -engineering undergraduate students from UnB and they worked physically in the
40   -same laboratory in the opposite of the senior. Each student had their own
41   -scheduler based on their class, it made complicated to implement pair
42   -programming. Also, they had a different area of interests. To cope with those
43   -diversity, we had two basic rules which guided the project organization:
  39 +engineering undergraduate students from UnB and they worked physically
  40 +in the same laboratory. Each student had their own schedule based on
  41 +their classes, what complicates the implementation of pair programming.
  42 +The senior developers tried to synchronize their schedule with the
  43 +students on their sub-team. To cope with this environment, we had a few
  44 +basic rules which guided the project organization:
44 45  
45 46 \begin{enumerate}
46   - \item Classes have to be the high priority for undergraduate students;
47   - \item Always work in pair (locally or remotely).
  47 + \item Classes have high priority for undergraduate students;
  48 + \item Work in pairs whenever possible (locally or remotely).
  49 + \item There must be one morning or afternoon per week when
  50 + \emph{everyone} should be together physically in the laboratory
  51 + (except of course the remote team members).
  52 + \item Every 3 to 4 months, the senior developers would fly in and work
  53 + alongside the students for a few days.
48 54 \end{enumerate}
49 55  
50   -With the aforementioned rules we divided all the project into four different
51   -teams: Colab, Noosfero, Design, and DevOps. Each team had one coach responsible
52   -for reducing the communication problem with the other teams and help the
53   -members to organize itself in the best way for everyone (always respecting the
54   -work time). The coach, was a normal student working in some of the teams with
55   -the extra duty of register the current tasks developed in the sprint and with
56   -the responsibility to talk with other teams. One important thing to notice is
57   -the mutability of the team and the coach, during the project many students
58   -changed between the teams to try different areas.
59   -
60   -One characteristic of the teams was the presence of (at least) one senior per
61   -team. This was essential, because hard decisions and complex problems were
62   -usually addressed to them, this relieved the coach duty to take a complicated
63   -technical decisions and encouraged students to be a coach. Lastly, the senior
64   -had to respect a rule number two and work with students, this was important to
65   -gave the undergraduate the opportunity to interact with a savvy professional in
66   -his area and keeping the knowledge flow in the project.
67   -
68   -Finally, we had to add two last elements of the team organization, that was
69   -essential for the project harmony: the meta-coach and professors. The former
70   -was a software engineer recently graduated and which wanted to keep working on
71   -the project, the latter were professors that orchestrated all the interactions
72   -between all members of the project. The meta-coach usually worked in one
73   -specific team and had the extra task of knowing the current status of all
74   -teams. Professors and meta-coaches worked together to reduce the communication
75   -problem between all the teams. Lastly, all the bureaucracy tasks was
76   -centralized in the professors.
77   -
78   -\subsection{Meetings}
79   -
80   -Brazilian government used to work with software development in a very
81   -traditional way, frequently they claim on documents and does not focus on what
82   -really matter (running software). This way of thinking caused to us a
83   -communication noise with MP, because they constantly tried to leverage on our
84   -work style. It was especially hard to convince them to accept the idea of open
85   -scope and agile development, but after months of labor and showing results they
86   -stopped resisting.
87   -
88   -We defined some level of meeting granularity to avoid to generate overheads to
89   -the developers. We had a strategical and validating meeting with MP (the
90   -former once in a month and the latter each 15th day), release plaining with the
91   -entire team (one per month), and finally a sprint planning (one each 15th day).
92   -Figure \ref{fig:meeting} is a diagram that represents our meeting organization.
  56 +With the aforementioned rules we divided all the project into four
  57 +different teams: Colab, Noosfero, Design, and DevOps. Each team had one
  58 +coach responsible for reducing the communication problem with the other
  59 +teams and help the members to organize themselves in the best way for
  60 +everyone (always respecting their work time). The coach was one of the
  61 +students working in some of the teams with the extra duty of registering
  62 +the current tasks developed in the sprint and with the responsibility to
  63 +talk with other teams. One important thing to notice is the mutability
  64 +of the team and the coach, during the project many students changed
  65 +between the teams to try different areas.
  66 +
  67 +One characteristic of the teams was the presence of (at least) one
  68 +senior per team. This was essential, because hard decisions and complex
  69 +problems were usually referred to them. This kept having to take
  70 +complicated technical decisions from the coach tole, what encouraged
  71 +students to be coaches. Lastly, the senior developers worked directly
  72 +with the students, and this was important to give the undergraduate the
  73 +opportunity to interact with a savvy professional in his area and to
  74 +keep the knowledge flowing in the project.
  75 +
  76 +Finally, we had to add two last elements of the team organization, that
  77 +was essential for the project harmony: the meta-coach and professors.
  78 +The former was a software engineer recently graduated and which wanted
  79 +to keep working on the project, the latter were professors that
  80 +orchestrated all the interactions between all members of the project.
  81 +The meta-coach usually worked in one specific team and had the extra
  82 +task of knowing the current status of all teams. Professors and
  83 +meta-coaches worked together to reduce the communication problem between
  84 +all the teams. Lastly, all the paperwork tasks, such as reporting on the
  85 +project progress to the Ministry, was handled by the professors.
  86 +
  87 +\subsection{Communication and management}
  88 +
  89 +Our team had many people working together, and most of the seniors worked in a
  90 +different city remotely. Also, we tried to keep our work completely clear to
  91 +the Brazilian government and citizens interested in following the project. To
  92 +handle those cases, we used a set of tools to communication and other to manage
  93 +the project.
  94 +
  95 +For communication between member in different places, we used: Google
  96 +handouts with tmate, IRC, and mailing lists. When one student had to
  97 +work in pair with a senior, normally, they used Google hangout for
  98 +communication and they shared a terminal session with tmate which allow
  99 +them to share the same terminal, with both typing and seeing the screen.
  100 +For questions and fast discussion, we used IRC. For general
  101 +notification, we used the mailing lists.
  102 +
  103 +For managing the project we used the SPB Portal itself; first to
  104 +validate it by ourselves, and also because it had all the required
  105 +tools. We basically created one wiki page per release Gitlab, one
  106 +milestone per sprint, and one or more issues for addressing each
  107 +feature. With this approach we achieved two important goals: keeping all
  108 +the management as close possible to to the source codem, and tracking
  109 +every feature developed during the project.
  110 +
  111 +\subsection{High-level project management and reporting}
  112 +
  113 +The Brazilian government used to work with software development in a
  114 +very traditional way. They would frequently focus on documents and not
  115 +on what was, in our opinion, what really matters: working software. This
  116 +dissonance caused us a communication noise with MP, because they would
  117 +often question our work style. It was especially hard to convince them
  118 +to accept the idea of open scope and agile development, but after months
  119 +of labor and showing results they stopped resisting.
  120 +
  121 +We defined some level of meeting granularity to avoid generating too
  122 +much overhead to the developers. We had a strategical and validating
  123 +meeting with MP (the former once in a month and the latter each 15th
  124 +day), release plaining with the entire team (one per month), and finally
  125 +a sprint planning (one each 15th day). Figure \ref{fig:meeting} is a
  126 +diagram that represents our meeting organization.
93 127  
94 128 \begin{figure}[hbt]
95 129 \centering
... ... @@ -98,36 +132,36 @@ Figure \ref{fig:meeting} is a diagram that represents our meeting organization.
98 132 \label{fig:meeting}
99 133 \end{figure}
100 134  
101   -In the strategical meeting we usually defined the priorities and new features
102   -with the Brazilian government (we always had to negotiate next steps with
103   -them). Normally the professors, the coach of each team, the meta-coach, and
104   -some employees of the MP join in this meeting. We usually discussed what the
105   -team already produced since our last meeting, and we establish the new features
106   -for the next release. Notice that just part of the team join in this meeting
107   -to avoid generating unnecessary overhead to the developers, but all the
108   -students interested to participate was allowed to join (many students wanted
109   -this experience during the project).
  135 +In the strategical meeting we usually defined the priorities and new
  136 +features with the Brazilian government. Normally the professors, the
  137 +coach of each team, the meta-coach, and some employees of the MP would
  138 +participate in this meeting. We usually discussed what the team already
  139 +produced since our last meeting, and established the new features for
  140 +the next release. Notice that just part of the team would join this
  141 +meeting to avoid generating unnecessary overhead to the developers, but
  142 +all the students interested to participate were allowed to join (many
  143 +students wanted this experience during the project).
110 144  
111 145 After the strategical meeting with Brazilian government agents, we had a
112 146 planning turn with all teams together. In this part, each team worked together
113   -to convert the MP wishes into small parts which was represented by the epics of
  147 +to convert the MP wishes into smaller parts which were represented by the epics of
114 148 the release. Each coach was responsible for conducting the planning, and after
115   -that register it on the project wiki (the wiki provided by Gitlab). With this
  149 +that record it on the project wiki (the wiki provided by Gitlab). With this
116 150 epic, each 14th day the team have generated their sprint scheduler (with small
117   -achievements mapped in issues).
  151 +achievements mapped to issues).
118 152  
119   -To keep the Brazilian government always updated, we invited them to work with
120   -us to validate the new features in progress. Normally we had a meeting each
121   -15th day. Basically, this was our work flow, we always kept everything
122   -extremely open to the MP (our way of work and open source projects) and to the
123   -team.
  153 +To keep the Brazilian government always updated, we invited them to work
  154 +with us to validate the new features in progress. Normally we had a
  155 +meeting each 15th day. Basically, this was our work flow, we always kept
  156 +everything extremely open to the MP (our way of working, and the one
  157 +often used by open source projects) and to the team.
124 158  
125   -To keep the track of all of those things we used the SPB, especially the
126   -Gitlab. Basically, we had:
  159 +To keep the track of all of those things we used the SPB itself,
  160 +especially Gitlab. Basically, we had:
127 161  
128 162 \begin{enumerate}
129 163 \item Project repository: We have one organization with many repositories
130   - \item Milestones: Each milestone is used to register a release
  164 + \item Milestones: Each milestone was used to register a release
131 165 \item Wiki: Each release has one page on wiki with the compilation of
132 166 strategical meeting
133 167 \item Issues: Each sprint planning generated issues, which we associated to
... ... @@ -135,32 +169,6 @@ Gitlab. Basically, we had:
135 169 with them. Finally each developer assigned the issue to itself.
136 170 \end{enumerate}
137 171  
138   -Notice that this workflow gave to us and to the Brazilian government agents a
139   -full traceability from high view of the feature to the low view (code). This
140   -provided to them a way to validate all worked done and proof the concept that
141   -work with open source project can give a proper view to them check.
142   -
143   -\subsection{Tools for communication and management}
144   -
145   -Our team had many people worked together, and most of the seniors worked in a
146   -different city remotely. Also, we tried to keep our work completely clear to
147   -the Brazilian government and citizens interested in follow the project. To
148   -handle those cases, we used a set of tools to communication and other to manage
149   -the project.
150   -
151   -For communication between member in different places, we used: google-talk with
152   -tmate, IRC, and mailing-list. When one student had to work in pair with a
153   -senior, normally, they used google-hangout for communication and they shared a
154   -session with tmate which allow them to share the same terminal. For questions
155   -and fast discussion, we used IRC. For general notification, we used the
156   -mailing-list.
157   -
158   -For managing the project we used the SPB Portal to validate it by ourselves and
159   -because it had all the required tools. We basically create one wiki page per
160   -release in Gitlab, one milestone per sprint, and one or more issues for address
161   -one user history. With this approach we achieve two important things: keep all
162   -the management close to the source code and tracked every feature developed by
163   -the project.
164   -
165   -%TODO: Ainda falta adicionar a parte da visita dos seniors e o turno sagrado
166   -
  172 +Notice that this workflow gave us and the Brazilian government agents
  173 +full traceability from a high level view of each feature to the lowest
  174 +level (code).
... ...