Commit be755023f74c2a0316b1c7c583efd0c2fa365e11
1 parent
15b52932
Exists in
master
and in
2 other branches
Re-organizing sections
Showing
14 changed files
with
185 additions
and
170 deletions
Show diff stats
opensym2017/content/03-arch.tex
| @@ -1,105 +0,0 @@ | @@ -1,105 +0,0 @@ | ||
| 1 | -\section{Architecture} | ||
| 2 | -\label{sec:architecture} | ||
| 3 | - | ||
| 4 | -%TODO: Kanashiro e Siqueira | ||
| 5 | - | ||
| 6 | -The two main requirements provided by the Brazilian Federal Government | ||
| 7 | -for the new platform were: | ||
| 8 | -% | ||
| 9 | -1) \textit{Integrate existing FOSS systems}, with minimal differences | ||
| 10 | -from their original versions. This way, the platform can benefit from | ||
| 11 | -improvements done by the upstream communities that provide those | ||
| 12 | -systems, and the maintenance effort that is specific for the SPB Portal | ||
| 13 | -should be reduced; | ||
| 14 | -% | ||
| 15 | -and | ||
| 16 | -2) \textit{Provide a consistent user interface} across the different | ||
| 17 | -systems, as well as centralized authentication. | ||
| 18 | - | ||
| 19 | -The first requirement was accomplished by dedicating specialized teams | ||
| 20 | -for each system that was being integrated. The teams would learn how to | ||
| 21 | -develop their assigned systems, and contribute the necessary features | ||
| 22 | -directly to the original communities, so that the version we used was | ||
| 23 | -not significantly different from the original. Of course, at times | ||
| 24 | -project deadlines forced us to use our own version before tho features | ||
| 25 | -were fully reviewed and integrated upstream to the original projects, | ||
| 26 | -but we managed to contribute the vast majority of the changes back. | ||
| 27 | - | ||
| 28 | -For the second requirement, we integrated a web integration platform | ||
| 29 | -called Colab\footnote{\url{https://github.com/colab/colab}}. Colab | ||
| 30 | -serves as a frontend for other web applications as a reverse proxy, | ||
| 31 | -manages authentication, and can apply changes to the HTML provided by | ||
| 32 | -the integrated applications in order to provide visual consistency. | ||
| 33 | -Colab had support for an initial set of applications (Trac, GNU Mailman, | ||
| 34 | -Apache Lucene) hard-coded; our team evolved Colab so that it can now | ||
| 35 | -receive plugins to add support for new applications with minimal changes | ||
| 36 | -to its existing core. We added support for the other applications used | ||
| 37 | -in the SPB platform: Noosfero, GitLab, and Mezuro. | ||
| 38 | - | ||
| 39 | -Noosfero\footnote{\url{http://noosfero.org/}} is a software for building | ||
| 40 | -social and collaboration networks. Besides the classical social | ||
| 41 | -networking features, it also provides publication features such as blogs | ||
| 42 | -and a general-purpose CMS (Content Management System). Most of the user | ||
| 43 | -interactions with SPB is through Noosfero: user registration, project | ||
| 44 | -home pages and documentation, and contact forms. | ||
| 45 | -GitLab\footnote{\url{http://gitlab.com/}} is a web-based Git repository | ||
| 46 | -manager with wiki pages and issue tracking features. | ||
| 47 | -Mezuro\footnote{\url{http://mezuro.org/}} is a platform to collect source code | ||
| 48 | -metric to monitor the internal quality of softwares written in C, C++, | ||
| 49 | -Java, Python, Ruby, and PHP. GNU Mailman is used for mailing lists. | ||
| 50 | - | ||
| 51 | -\begin{figure}[hbt] | ||
| 52 | - \centering | ||
| 53 | - \includegraphics[width=\linewidth]{figures/arch.png} | ||
| 54 | - \caption{SPB architecture overview.} | ||
| 55 | - \label{fig:architecture} | ||
| 56 | -\end{figure} | ||
| 57 | - | ||
| 58 | -The conceptual architecture of the platform is presented in Figure | ||
| 59 | -\ref{fig:architecture}. Colab initially handles all user interaction, | ||
| 60 | -directing requests to one of the integrated applications. It | ||
| 61 | -post-processes responses from the applications to apply a consistent | ||
| 62 | -visual appearance, manages authentication, and provides a unified search | ||
| 63 | -functionality: instead of using the redundant restricted search | ||
| 64 | -functionality of each application, a search in the SPB portal might | ||
| 65 | -return content from any of the applications, be it web pages, mailing | ||
| 66 | -list posts, or source code. | ||
| 67 | - | ||
| 68 | -%TODO: deixar coeso daqui para baixo | ||
| 69 | - | ||
| 70 | -\begin{figure*}[hbt] | ||
| 71 | - \centering | ||
| 72 | - \includegraphics[width=\linewidth]{figures/arch2.png} | ||
| 73 | - \caption{Instanciation view of the SPB architecture.} | ||
| 74 | - \label{fig:architecture2} | ||
| 75 | -\end{figure*} | ||
| 76 | - | ||
| 77 | -In real, the SPB platform was deployed in 7 virtual machines with different functions, | ||
| 78 | -as we can see in Figure \ref{fig:architecture2}. | ||
| 79 | - | ||
| 80 | -The \textit{reverseproxy} handles the HTTP requests and redirects them to the | ||
| 81 | -\textit{integration}, the \textit{email} sends and receives e-mails on behalf | ||
| 82 | -of the platform and the \textit{monitor} keeps the entire environment tracked. | ||
| 83 | -These three \textit{VMs} mentioned - \textit{reverseproxy}, \textit{email} and | ||
| 84 | -\textit{monitor} - are accessible via Internet and the other ones are only | ||
| 85 | -available in the local network created between them. | ||
| 86 | - | ||
| 87 | -\textit{Integration} works as a second layer of proxy beneath | ||
| 88 | -\textit{reverseproxy}, any request to the platform will be handled by it. The | ||
| 89 | -Colab service provides interface, authentication and search engine integration | ||
| 90 | -among all the services. When a request is received to a specific service, | ||
| 91 | -Colab authenticates the user in the target tool, sends the request and makes a | ||
| 92 | -visual transformation in the HTML page which is the content of the response. | ||
| 93 | -Another user-oriented feature is the integrated search engine, when the user | ||
| 94 | -want to find something in the platform Colab will perform the search in the | ||
| 95 | -whole databases. Colab itself provides a web interface for GNU Mailman and we | ||
| 96 | -have two others integrated tools in \textit{integration}: Gitlab and Prezento. | ||
| 97 | -Gitlab provides web interface for Git repositories and issues tracker, and | ||
| 98 | -Prezento is a front-end for source code static analysis. | ||
| 99 | - | ||
| 100 | -The source code static analysis is performed by \textit{mezuro}. It runs some | ||
| 101 | -static analysis tools on source code stored in repository and provide this data | ||
| 102 | -to Prezento. A social network and CMS (Content Manager System) is provided by | ||
| 103 | -Noosfero in \textit{social}, and the databases of all tools with a cache | ||
| 104 | -service are in \textit{database}. | ||
| 105 | - |
opensym2017/content/04-features.tex
| @@ -0,0 +1,105 @@ | @@ -0,0 +1,105 @@ | ||
| 1 | +\section{Architecture} | ||
| 2 | +\label{sec:architecture} | ||
| 3 | + | ||
| 4 | +%TODO: Kanashiro e Siqueira | ||
| 5 | + | ||
| 6 | +The two main requirements provided by the Brazilian Federal Government | ||
| 7 | +for the new platform were: | ||
| 8 | +% | ||
| 9 | +1) \textit{Integrate existing FOSS systems}, with minimal differences | ||
| 10 | +from their original versions. This way, the platform can benefit from | ||
| 11 | +improvements done by the upstream communities that provide those | ||
| 12 | +systems, and the maintenance effort that is specific for the SPB Portal | ||
| 13 | +should be reduced; | ||
| 14 | +% | ||
| 15 | +and | ||
| 16 | +2) \textit{Provide a consistent user interface} across the different | ||
| 17 | +systems, as well as centralized authentication. | ||
| 18 | + | ||
| 19 | +The first requirement was accomplished by dedicating specialized teams | ||
| 20 | +for each system that was being integrated. The teams would learn how to | ||
| 21 | +develop their assigned systems, and contribute the necessary features | ||
| 22 | +directly to the original communities, so that the version we used was | ||
| 23 | +not significantly different from the original. Of course, at times | ||
| 24 | +project deadlines forced us to use our own version before tho features | ||
| 25 | +were fully reviewed and integrated upstream to the original projects, | ||
| 26 | +but we managed to contribute the vast majority of the changes back. | ||
| 27 | + | ||
| 28 | +For the second requirement, we integrated a web integration platform | ||
| 29 | +called Colab\footnote{\url{https://github.com/colab/colab}}. Colab | ||
| 30 | +serves as a frontend for other web applications as a reverse proxy, | ||
| 31 | +manages authentication, and can apply changes to the HTML provided by | ||
| 32 | +the integrated applications in order to provide visual consistency. | ||
| 33 | +Colab had support for an initial set of applications (Trac, GNU Mailman, | ||
| 34 | +Apache Lucene) hard-coded; our team evolved Colab so that it can now | ||
| 35 | +receive plugins to add support for new applications with minimal changes | ||
| 36 | +to its existing core. We added support for the other applications used | ||
| 37 | +in the SPB platform: Noosfero, GitLab, and Mezuro. | ||
| 38 | + | ||
| 39 | +Noosfero\footnote{\url{http://noosfero.org/}} is a software for building | ||
| 40 | +social and collaboration networks. Besides the classical social | ||
| 41 | +networking features, it also provides publication features such as blogs | ||
| 42 | +and a general-purpose CMS (Content Management System). Most of the user | ||
| 43 | +interactions with SPB is through Noosfero: user registration, project | ||
| 44 | +home pages and documentation, and contact forms. | ||
| 45 | +GitLab\footnote{\url{http://gitlab.com/}} is a web-based Git repository | ||
| 46 | +manager with wiki pages and issue tracking features. | ||
| 47 | +Mezuro\footnote{\url{http://mezuro.org/}} is a platform to collect source code | ||
| 48 | +metric to monitor the internal quality of softwares written in C, C++, | ||
| 49 | +Java, Python, Ruby, and PHP. GNU Mailman is used for mailing lists. | ||
| 50 | + | ||
| 51 | +\begin{figure}[hbt] | ||
| 52 | + \centering | ||
| 53 | + \includegraphics[width=\linewidth]{figures/arch.png} | ||
| 54 | + \caption{SPB architecture overview.} | ||
| 55 | + \label{fig:architecture} | ||
| 56 | +\end{figure} | ||
| 57 | + | ||
| 58 | +The conceptual architecture of the platform is presented in Figure | ||
| 59 | +\ref{fig:architecture}. Colab initially handles all user interaction, | ||
| 60 | +directing requests to one of the integrated applications. It | ||
| 61 | +post-processes responses from the applications to apply a consistent | ||
| 62 | +visual appearance, manages authentication, and provides a unified search | ||
| 63 | +functionality: instead of using the redundant restricted search | ||
| 64 | +functionality of each application, a search in the SPB portal might | ||
| 65 | +return content from any of the applications, be it web pages, mailing | ||
| 66 | +list posts, or source code. | ||
| 67 | + | ||
| 68 | +%TODO: deixar coeso daqui para baixo | ||
| 69 | + | ||
| 70 | +\begin{figure*}[hbt] | ||
| 71 | + \centering | ||
| 72 | + \includegraphics[width=\linewidth]{figures/arch2.png} | ||
| 73 | + \caption{Instanciation view of the SPB architecture.} | ||
| 74 | + \label{fig:architecture2} | ||
| 75 | +\end{figure*} | ||
| 76 | + | ||
| 77 | +In real, the SPB platform was deployed in 7 virtual machines with different functions, | ||
| 78 | +as we can see in Figure \ref{fig:architecture2}. | ||
| 79 | + | ||
| 80 | +The \textit{reverseproxy} handles the HTTP requests and redirects them to the | ||
| 81 | +\textit{integration}, the \textit{email} sends and receives e-mails on behalf | ||
| 82 | +of the platform and the \textit{monitor} keeps the entire environment tracked. | ||
| 83 | +These three \textit{VMs} mentioned - \textit{reverseproxy}, \textit{email} and | ||
| 84 | +\textit{monitor} - are accessible via Internet and the other ones are only | ||
| 85 | +available in the local network created between them. | ||
| 86 | + | ||
| 87 | +\textit{Integration} works as a second layer of proxy beneath | ||
| 88 | +\textit{reverseproxy}, any request to the platform will be handled by it. The | ||
| 89 | +Colab service provides interface, authentication and search engine integration | ||
| 90 | +among all the services. When a request is received to a specific service, | ||
| 91 | +Colab authenticates the user in the target tool, sends the request and makes a | ||
| 92 | +visual transformation in the HTML page which is the content of the response. | ||
| 93 | +Another user-oriented feature is the integrated search engine, when the user | ||
| 94 | +want to find something in the platform Colab will perform the search in the | ||
| 95 | +whole databases. Colab itself provides a web interface for GNU Mailman and we | ||
| 96 | +have two others integrated tools in \textit{integration}: Gitlab and Prezento. | ||
| 97 | +Gitlab provides web interface for Git repositories and issues tracker, and | ||
| 98 | +Prezento is a front-end for source code static analysis. | ||
| 99 | + | ||
| 100 | +The source code static analysis is performed by \textit{mezuro}. It runs some | ||
| 101 | +static analysis tools on source code stored in repository and provide this data | ||
| 102 | +to Prezento. A social network and CMS (Content Manager System) is provided by | ||
| 103 | +Noosfero in \textit{social}, and the databases of all tools with a cache | ||
| 104 | +service are in \textit{database}. | ||
| 105 | + |
opensym2017/content/05-process.tex
opensym2017/content/06-ux.tex
| @@ -1,33 +0,0 @@ | @@ -1,33 +0,0 @@ | ||
| 1 | -\section{User eXperience evolution} | ||
| 2 | - | ||
| 3 | -The integration of collaborative environments goes beyond functional aspects. | ||
| 4 | -Offering the population an unified experience across these environments has | ||
| 5 | -been the key to encourage the use of the platform as it reduces the perception | ||
| 6 | -of complexity. Thus, the SPB Portal information architecture was redesigned | ||
| 7 | -to provide a transparent navigation and to reach users with different profiles. | ||
| 8 | -A process of harmonization has been employed on the interaction models of each | ||
| 9 | -tool to reduce the learning curve. At the same time, a new visual style was | ||
| 10 | -created to unify the navigation experience and to comply with the guidelines of | ||
| 11 | -the digital communication identity standard established by the Federal | ||
| 12 | -Government. | ||
| 13 | - | ||
| 14 | -With the increase in system features and the addition of new tools, the | ||
| 15 | -visual style has steadily evolved to keep the navigation unified. Moreover, | ||
| 16 | -tools from different backgrounds, which in many cases provide similar | ||
| 17 | -functionality, prompted the development of an unified interface. Some | ||
| 18 | -features, such as search and user profile editing were eliminated from | ||
| 19 | -the individual applications, and implemented centrally to ensure a | ||
| 20 | -consistent look and feel. | ||
| 21 | - | ||
| 22 | -Another challenge was responsive web design. The integrated applications | ||
| 23 | -had varying degrees of support for responsiveness, and the common | ||
| 24 | -interface had to adapt for each individual scenario. In particular | ||
| 25 | -Noosfero did not yet have a responsive design; we engaged in its | ||
| 26 | -development and contributed towards that goal. | ||
| 27 | - | ||
| 28 | -After the initial release of the new SPB Portal in 2014, several | ||
| 29 | -validations activities were implemented in 2015 and 2016. The aim was to | ||
| 30 | -provide the most wanted features by casual users (such as public | ||
| 31 | -servants interested in downloads and documentation) immediately, while | ||
| 32 | -allowing more experienced users (such as developers) to easily drill down | ||
| 33 | -to the details. |
opensym2017/content/07-finals.tex
| @@ -1,13 +0,0 @@ | @@ -1,13 +0,0 @@ | ||
| 1 | -\section{Final remarks} | ||
| 2 | - | ||
| 3 | -The portal is available at \url{softwarepublico.gov.br}. All | ||
| 4 | -documentation, including detailed architecture and operation manuals are | ||
| 5 | -also available\footnote{\url{https://softwarepublico.gov.br/doc/} | ||
| 6 | -(in Portuguese only at the moment)}). | ||
| 7 | -% | ||
| 8 | -All the integrated tools are FOSS and our contributions were published | ||
| 9 | -in open repositories, available on the SPB Portal itself. We also | ||
| 10 | -contributed these features back to the respective communities: that | ||
| 11 | -benefits those communities, as well as us since we can share future | ||
| 12 | -development and maintenance effort with other organizations that | ||
| 13 | -participate in their projects. |
| @@ -0,0 +1,33 @@ | @@ -0,0 +1,33 @@ | ||
| 1 | +\section{User eXperience evolution} | ||
| 2 | + | ||
| 3 | +The integration of collaborative environments goes beyond functional aspects. | ||
| 4 | +Offering the population an unified experience across these environments has | ||
| 5 | +been the key to encourage the use of the platform as it reduces the perception | ||
| 6 | +of complexity. Thus, the SPB Portal information architecture was redesigned | ||
| 7 | +to provide a transparent navigation and to reach users with different profiles. | ||
| 8 | +A process of harmonization has been employed on the interaction models of each | ||
| 9 | +tool to reduce the learning curve. At the same time, a new visual style was | ||
| 10 | +created to unify the navigation experience and to comply with the guidelines of | ||
| 11 | +the digital communication identity standard established by the Federal | ||
| 12 | +Government. | ||
| 13 | + | ||
| 14 | +With the increase in system features and the addition of new tools, the | ||
| 15 | +visual style has steadily evolved to keep the navigation unified. Moreover, | ||
| 16 | +tools from different backgrounds, which in many cases provide similar | ||
| 17 | +functionality, prompted the development of an unified interface. Some | ||
| 18 | +features, such as search and user profile editing were eliminated from | ||
| 19 | +the individual applications, and implemented centrally to ensure a | ||
| 20 | +consistent look and feel. | ||
| 21 | + | ||
| 22 | +Another challenge was responsive web design. The integrated applications | ||
| 23 | +had varying degrees of support for responsiveness, and the common | ||
| 24 | +interface had to adapt for each individual scenario. In particular | ||
| 25 | +Noosfero did not yet have a responsive design; we engaged in its | ||
| 26 | +development and contributed towards that goal. | ||
| 27 | + | ||
| 28 | +After the initial release of the new SPB Portal in 2014, several | ||
| 29 | +validations activities were implemented in 2015 and 2016. The aim was to | ||
| 30 | +provide the most wanted features by casual users (such as public | ||
| 31 | +servants interested in downloads and documentation) immediately, while | ||
| 32 | +allowing more experienced users (such as developers) to easily drill down | ||
| 33 | +to the details. |
| @@ -0,0 +1,13 @@ | @@ -0,0 +1,13 @@ | ||
| 1 | +\section{Final remarks} | ||
| 2 | + | ||
| 3 | +The portal is available at \url{softwarepublico.gov.br}. All | ||
| 4 | +documentation, including detailed architecture and operation manuals are | ||
| 5 | +also available\footnote{\url{https://softwarepublico.gov.br/doc/} | ||
| 6 | +(in Portuguese only at the moment)}). | ||
| 7 | +% | ||
| 8 | +All the integrated tools are FOSS and our contributions were published | ||
| 9 | +in open repositories, available on the SPB Portal itself. We also | ||
| 10 | +contributed these features back to the respective communities: that | ||
| 11 | +benefits those communities, as well as us since we can share future | ||
| 12 | +development and maintenance effort with other organizations that | ||
| 13 | +participate in their projects. |
opensym2017/spb.tex
| @@ -152,11 +152,14 @@ | @@ -152,11 +152,14 @@ | ||
| 152 | %------------------------------------------------------------------------------ | 152 | %------------------------------------------------------------------------------ |
| 153 | \input{content/01-introduction} | 153 | \input{content/01-introduction} |
| 154 | \input{content/02-spb} | 154 | \input{content/02-spb} |
| 155 | -\input{content/03-arch} | ||
| 156 | -\input{content/04-features} | ||
| 157 | -\input{content/05-process} | ||
| 158 | -\input{content/06-ux} | ||
| 159 | -\input{content/07-finals} | 155 | +\input{content/03-requirements} |
| 156 | +\input{content/04-process} | ||
| 157 | +\input{content/05-architecture} | ||
| 158 | +\input{content/06-features} | ||
| 159 | +\input{content/07-ux} | ||
| 160 | +\input{content/08-contributions} | ||
| 161 | +\input{content/09-lessons} | ||
| 162 | +\input{content/10-finals} | ||
| 160 | 163 | ||
| 161 | %------------------------------------------------------------------------------ | 164 | %------------------------------------------------------------------------------ |
| 162 | \bibliographystyle{SIGCHI-Reference-Format} | 165 | \bibliographystyle{SIGCHI-Reference-Format} |