Ok pushed v2: eupharis@d3ee3df

Alright, I'll be darned if I can find it. Maybe I forgot to press the Comment button or something, that's been know to happen.

Anyway, short story is, next step is to pull together some acceptance tests. Kind of at the same time we should noodle out an implementation strategy, like what comes first, how big are the chunks, what comes after, etc.

The acceptance tests are in features/. They're written in Cucumber and executed by behave. Let me know if you've worked with those before. The steps (code that actually runs during the test) are in features/steps/. Maybe you can have a look around there a give me an idea how much sense it makes to you and what you need to help explain.

I'm thinking the first thing we should set our sights on is getting through the use case of adding plain text to a single header (not footer) for a single section document. That will give us more or less end-to-end capability, and everything else should be able to be built on that.

In general, the first step is test to be able to read the item, only after that to write the item. The reason being you need the read ability to test the write ability. Also write tends to build on the foundations of read so it all works out nicely. So I'm thinking the first few acceptance tests might be:

Given a section
  Then section.header is a Header object

Given a header having a definition
  Then header.is_linked_to_previous is False

Given a header having a definition
  Then header.text is the text contained in the header

And we'd proceed on from there is some rational way. These are just sketches, I think it will take a little more noodle time to get them right. In general we do one acceptance test at a time, but sometimes it makes sense to do two or three together. Getting it to the point where it runs properly but fails (due to lack of implementation), that's a commit and then it's on to unit-test/code cycles (one commit per test) until the acceptance test passes. Usually it's maybe three unit tests per acceptance test, but it varies, could be one, could be ten (but probably never twenty, that would be a test smell).

Anyway, have a look around and let me know how it goes and we'll go from there :)

Ok sweet. I really like the idea of adding a plain text header to a single section document and then going from there!

I've never heard of Behave/Cucumber.

I've thought before "wouldn't it be nice if the product people could just write high-level tests." There is a ton of overlap between a really well thought out ticket and a good test. Also in the context of web programming, it would help them to answer the question "is this frontend or backend?" just by reading the acceptance test.

Behave/Cucumber seems to do exactly this!

Cucumber doesn't seem too complicated. How about I write a few appropriately failing behavior tests later this week or early next week and we can talk about them?

perfect :)

So I want to be able to to refer back to all the discussion here. Not 100% sure what a rebase and force push would do to all the comments.

I cut a fresh branch directly off python-openxml:feature/header, created a new PR, and added the first failing acceptance tests. We can continue on from there if that works for you!

#291

Sure, that sounds good @eupharis. We're still experimenting with workflow, so trying out this option is a good exercise. We've tried the forced-push option, and it's not awful, but you're quite right, the discussion on commits that got rewritten gets hard to access afterward. It's still there (at least for a while), but you have to retain a reference to the particular commit (I usually just dig back in old emails if I need it :). So it's not a terrific option.

I had been keen to keep the pull requests limited in number, and I do think there's a place for forced pushes in the process, but I'm starting to think it's not a bad thing if a feature ends up taking three or four PRs by the time it's done. Perhaps especially the enhancement request/analysis commit, given that often ends up generating a lot of discussion that can come in handy much later in the implementation.

So we'll give it a shot here and see where it takes us :)

I should be able to have a look at the new one this evening.