...

Project workflow - explanation

We are currently applying pretty much our own version of Agile development on this project, this might be a bit vague, but it is realistic. This means we have no clear overall design document yet, but are building this as we go. The design elements that we have decided upon (such as using a micro-service architecture) can be found on this confluence wiki, especially the design pages, new design decisions should be put here there as well. The fact that this is an voluntary international open-source project makes defining clear sprints and deadlines very hard, therefore we have our own version of this: Sprints are voluntary for each person depending on their available time and commitment. We have strive for somewhat regular meetings on Monday (somewhere between 20:00 - 22:00 CET) to discuss design decisions, quickly exchange what we have done and plan to do the coming week, and other things that come up. Aside from these meetings quick communication is facilitated using Slack, more in-depth discussions are facilitated by issues on JIRA, decisions are finalized by putting them on Confluence.

Aside from this Agile approach we intend to set up a continuous integration workflow (this is currently not the case yet) by making make use of the git branching model, automated testing using ..what?.. and then automated deployment on fraktis, our live staging (testing) environment running on model and automated integration tests using Travis CI. Deployment is by now almost automated on a virtual machine hosted on fraktis, TITAN.

Our internal organization is non-hierarchical, meaning there is no real 'boss', although we do have divided roles and responsibilities. Derk Snijders is currently the 'project manager' as he is also assigned by the CD to work on the project from Brussels, this means he has the responsibility to maintain the overview, check whether we are going in the right direction and maintain and assign issues and documentation. Other responsibilities are mostly split between the micro services, check the micro services overview for this.

The goal is to set regular releases (with a deadline) which we hope to achieve in order to have a common goal to work to. When we fail to achieve this there is no real consequence to it (yet?) other than having even more reason to do our very best for the next deadline! Additionally once we have something worth showing we want to let the network know! Currently the plan is to have the minimum viable product in working shape and ready for testing before going all out on the promotion.

Development Tools

We make use of the following tools to assist us in developing the MyAEGEE OMS:

• Slack
  • Used for quick questions and general conversation.
• Confluence
  • Used to document the design (decisions) of the project to have it all in 1 space as well as to have the knowledge available to whomever needs it.
• JIRA
  • Issue tracker, used to indicate to-do's and discuss these to-do's
• Git
  • Used as a version control and collaboration tool
• Should things like docker or proxmos be mentioned here?

We tried working with releases, this did not really work yet, instead we are using JIRA in order to rank issues by priority as well as the project manager making sure work is correctly prioritized.

This is a simpler version of the processes section in the Project Plan, it is strongly recommended to read that as well.

Development Tools

See the tools section in the Project Plan, additionally see the processes section in the project plan on how they are used.

General guidelines

This is a list of rules and tips you should follow

• Rules:
  • Use the Git branching model described here
  • Quick questions can be asked on Slack, more in depth questions should go through JIRA
  • Check how we use JIRA
  • Everything should be written in English
  • Coding style
    • Not defined yet - 

      Jira Legacy
      server JIRA (oms-project.atlassian.net) columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId edf3f91b-210c-3cfc-933c-f8d8084c5f2c key GENERAL-83

  • Everyone should have a chance to discuss major design decisions before they are implemented
    
  • Everything will be available as part of an open-source license
• Tips:
  • Talk to the person responsible before you start working on something
  • There is no (regular) amount of time you need to have available, it is a fully voluntary project
  • While we are using an Agile approach, this does not remove the fact that documentation is important. Document and update design decisions as they are made and changed.
  • Voice your opinion about something you disagree with, everyone should be open for discussing as long as it happens in a respectful way.
  • Really, use this workflow!

Developing your own micro service - workflow

While using Agile means that the end functionalities of certain aspects of the software are not yet known at the start, there still needs to be some design done, as an initial goal. Therefore each micro service should start out having a single and clearly defined goal (defined through the responsibilities and functionalities). The definition of what defines 'single' and 'clearly defined' is obviously not set in stone however, therefore a micro service should be proposed and allow some time for discussion among the developers before being implemented. During the process of developing a micro service it is very well possible that certain changes in the goal are made. This is not a problem as long as these changes are again allowed discussion and are thought out before implementing. A very crucial part in this development process of changing goals is to keep the documentation up-to-date, that way other developers can also stay up-to-date with that micro service and adapt to it accordingly.

This process of developing a micro service should be, as everything in the project should be, proposed and discussed using JIRA issues and afterwards be reflected in their documentation on Confluence.

Additionally, the development of the micro services should respect our overall workflow and should therefor follow the Git workflow and JIRA workflow as defined on their respective Confluence pages.

Micro service requirements

Basically the rule of micro services is that everything is allowed, as long as it complies with the communication requirements set out.some common rules are followed:

• Responsibilities
  • Every micro service needs to manage its own data
  • Should be more general responsibilities right?
• API
  • The API should abide the general API rules laid out.
  • The API should be well documented.
• Backend requirements
  • A backend is required for every micro service.
  • There are no requirements for the implementation language as long as it can expose a public API, however have a look at the list of technologies recommended.
  • Every backend needs to correctly implement the handshake.
• Frontend requirements
  • The frontend in its entirety is optional, a micro service can have just a backend.
  • When implemented it is required to make use of Angular JS (version 1.5.5) and Angular UI Router (version 0.2.15).
  • Every frontend needs to correctly implement the handshake.
  • Should a frontend be separated from the backend within the micro service?.
• Requirements
  • Follow the standardized requirements.
• Documentation
  • An accurate and up-to-date description of the responsibilities and functionalities.
  • Design decisions should be discussed and the arguments should be available (and remain available) for public viewing, this is achieved by discussing using JIRA
• The usage of an existing third party framework should be discussed first. (This is to avoid too many dependencies)

Starting work on a new micro service

When you are planning to start working on a new micro service you should stick to the following workflow:

1. Check the micro service overview
   
   1. Check the existing micro services for what is already implemented or planned and make sure your idea deserves it own micro service
2. Define responsibilities and functionalities
   1. Define what your micro service will be responsible for and what the functionalities will be and document this at the appropriate locations.
3. Brainstorm the idea
   1. Throwing out a message in slack about your idea will likely fire up a (quick) brainstorm about the microservice, often providing useful feedback.
4. Check the list of technologies
   1. Decide what technology would best suit your new micro service and consider the recommendations on the technologies page.
5. Think about the API
   1. Think about what kind of things your service would need to expose in order to achieve its functionalities, as well as what you would need from other micro services.
6. Make an initial design
   1. Choose a design (architecture / pattern) that you think would suit your micro service and document it.
7. Discuss with others!
   1. You can of course (and maybe should) start discussing your micro service from the very start of your idea.
8. Start implementing
   1. Don't forget to change your design based on the outcome of the discussion and keep updating the documentation as you go.

...