Skip to content

Add a motivation section #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 9, 2018
Merged

Add a motivation section #6

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5af0b04
Add a motivation section
Oct 8, 2018
86f8e6d
Add some suggestions from @dnadales
Oct 9, 2018
8411340
Finish off the issues section
Oct 9, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 83 additions & 9 deletions github-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,79 @@
# Development github process #


Github has in built tooling for lightweight, developer focused project
management. We can leverage these tools to track work in a way that makes sense
to developers. There's extensive documentation on how to use these tools in the
[GitHub Guides](https://guides.github.com/) website. In particular the
[Mastering Issues](https://guides.github.com/features/issues/) documentation is
worth reviewing.
We have a pretty large development team spread across several teams. These teams
have somewhat different focuses, from formal methods engineers developing proofs
and executable specs, to more implementation focused teams. We also use several
different programming languages now. All of these separate streams of work need
to integrate with the larger mission of IOHK and the management processes
that keep track of large, interconnected projects.

## Motivation ##

The aim of this document is to lay out a lightweight, developer focused set of
best practices for managing work and tracking progress using github. These
processes are owned by the developers themselves and everyone should feel
empowered to suggest improvements on an ongoing basis as we figure out what
works and what could be improved.

Teams that require amendments to this process should overlay this document with
any tweaks or changes that they wish to make for their own day to day work
flows. We will also establish a regular feedback loop so that where appropriate
we can incorporate these changes to the main process. The aim here is that
everyone should be doing roughly the same thing, and any differences should be
outlined. This is so that we can easily implement exchange or liaison programs
between teams and developers can slot into other teams easily when required.

## Principles ##

The software development process should set out the basic day to day workflow
that developers can follow. This workflow should strive for the optimal balance
between allowing the developer to focus on the most high value work and granting
the business an overview of what's in flight and when to expect delivery. To
achieve these competing aims and decide on the trade offs, we should be guided
by some principles. These are:

### Clarity ###

Things that should be clear from applying the process laid out in this document
are:

* What each team is working on and the importance of that delivery to the "big
picture".
* What dependencies pieces of work have from other teams (and vice versa).
* As accurate as possible view of when the pieces of work in flight can be
expected to be delivered.


### Lightweight ###

The process should be easy to understand and implement and should impose the
minimum overhead on developers over and above general development tasks. The
ideal here is something that's integrated with developer tooling and automatic.

### Changeable ###

The process should be changeable as requirements shift or improvements are
identified.

### Integration ###

These processes should offer easy integration points to other managements
systems and processes. For example, it should be straightforward for a project
manager to get an overview of progress without having to pull developers into a
meeting or otherwise interrupt their flow.


## GitHub benefits ##


Github has in built tooling for developer centric project management. We can
Copy link
Contributor

@dnadales dnadales Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we know which information management wants? Do they care about having some issues and boards in YouTrack, and some boards and issues in Github? I'm all in for "developer centric" but I don't want this feature biting us in the back ;)

Copy link
Contributor Author

@commandodev commandodev Oct 8, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key takeaway from the process the @vincenthz et al have built is having a well defined line where the software process starts. Below this line external parties from the software dev team shouldn't need to know too much. The delineation point I'm aiming for here is the milestone. Project managers shouldn't care too much about issues/PRs - their interest should stop at "how complete is this milestone" and what is its due date.

We do need to capture this in the document somewhere - but I want to avoid too much of how things are done now seeping into a set of documents for how we do things in future if that makes sense?

Copy link
Contributor

@dnadales dnadales Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Below this line external parties from the software dev team should need to know too much.

Should or shouldn't?

Copy link
Contributor

@dnadales dnadales Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Project managers shouldn't care too much about issues/PRs - their interest should stop at "how complete is this milestone" and what is its due date.

I asked this, because I was asked by managers "which issues do you worked on" (which sounded a bit like micro-managing, but anyway). However does this assumes that management will look at our milestones in Github? I wouldn't like having to enter this information in some other system, since it is error prone and duplicates effort.

Copy link
Contributor

@dnadales dnadales Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do need to capture this in the document somewhere - but I want to avoid too much of how things are done now seeping into a set of documents for how we do things in future if that makes sense?

Sure! That makes sense. I guess we want a very short document describing our super lightweight process. However we might need to mention somewhere (like in an appendix or separate document) what are the requirements for a development process and why, so that we have some references in case somebody asks why the current methods are not good enough.

But of course, we don't have to do this in this PR.

Copy link
Contributor Author

@commandodev commandodev Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was shouldn't I've changed it.

The intention here is that PMs should be able to get an accurate idea where things are from the milestones and really shouldn't care about which issues have been worked on (or in the case of the less technical PM even what those issues really mean)

leverage these tools to track work in a way that makes sense to developers.
There's extensive documentation on how to use these tools in the [GitHub
Guides](https://guides.github.com/) website. In particular the [Mastering
Issues](https://guides.github.com/features/issues/) documentation is worth
reviewing.

### Separation of managing work and reporting on work ###

Using github gives us a clear separation between things that developers care
Expand All @@ -25,17 +89,27 @@ the standard tools in PRs (for example commenting that a PR "Closes

[Automation](https://help.github.com/articles/configuring-automation-for-project-boards/)


## <a id="project"></a>Projects ##

Projects can be internal to a GitHub repository, or a GitHub organisation. They
have a kanban like board where all the issues and pull requests that are tagged
to that project appear. As issues are closed and PRs merged the cards on the
board are moved to done, but moving them to in progress is a manual process.

## <a id="milestone"></a>Milestones ##

A github milestone is a unit of delivery. A grouping of individual [prs](#pr) or
[issues](#issue) that are the break down of a deliverable chunk of work.
[issues](#issue) that are the break down of a deliverable chunk of work. A
milestone is internal to a GitHub repository.

## <a id="pull request"></a>Pull Requests ##

Pull requests are an intention to merge code into the main line of development
(or another branch). PRs are opened when a feature or other chunk of work is
development complete for review and possible further tweaks by other developers.

## <a id="issue"></a>Issues ##

An issue is a breakdown of work from a [milestone](#milestone). The general rule
of thumb for these is as granular as possible, but
of thumb for these is as granular as possible, but ideally less than a couple of
days work. The more granular the issue, the more precise the estimate can be.