Mailinglist Archive: yast-devel (144 mails)

< Previous Next >
Re: [yast-devel] Discussion - How should look new module written in ruby
Dne 1.8.2013 15:26, Vladimir Moravec napsal(a):
Dne 1.8.2013 09:53, Josef Reidinger napsal(a):
1) for skeleton I think that skeleton should be as small as possible,
so move all repeating code to own method provided by a module (that is
nice feature of rails, you can start really quickly ). And I think we
should make clear difference between leaf module and module that can be
reused by other modules. Because often there are Yast modules that have
modules, but they use it themself exclusivelly. For such case now should
be "lib" directory where is private Yast module code such us specific
configuration logic or module specific dialogs. Advantage of such step
is that you need not care about backward compatibility, as there is no
public API and we can use all ruby features.
Does this mean we'll get an additional dir called 'lib' while the 'src'
dir will serve
for module public API?

No, the "lib" directory will be at the same level as "modules", "include", etc.:

/src/lib
/src/modules
/src/include

Are there some best-practice tips how to
structure that 'lib' dir
to keep the layout similar between yast modules?

We'll need to invent some.

5) testing framework. We definitively need new one, old one is really
horrible to use and fragile. Ruby provide a lot of nice test
frameworks, the well known are Test:Unit[2] ( classical test unit
framework with asserts ) and RSpec that is designed to fit nice for TDD
[3]. I personally use for a long time Test:Unit and try RSpec few
months ago and I really like RSpec, especially how tests looks like and
how nice is its output.
In case we go with RSpec we should be aware of the plans of the rspec
dev team, mainly
of the DSL "should"-based syntax change which is going to be depreciated
in the Rspec 3 . This link
is worth of reading:
http://myronmars.to/n/dev-blog/2013/07/the-plan-for-rspec-3

Thanks a lot for this link, I didn't know about the described changes.

6) Documentation. For code documentation we translate comments to
YARD[4]. But there is also documentation that sits around in docbook
format. I found quite hard to write new parts of documentation and keep
it up-to-date. I found tool that can convert docbook to textual based
markdown format[5]. And I also thing that documentation should be
together with code and also examples should live with code. YARD
support it in quite nice way (support inlined markdown). See e.g.
documentation of ActiveRecord::Base which lives together code and how
it can look like [6].
I fully agree, but beside that what I'm missing is the basic
documentation or summary
shown on github index page for every yast module, it's strange not
having a short README
file in the repo root.

I agree, basic README.md for each module would be nice. It should at least describe the module and contain a pointer to more general development information (currently in openSUSE wiki).

When discussing docs, will we be using the github wiki for the general
FAQs or HOWTOs?

AFAIK we use openSUSE wiki now. This is both good and bad.

Good because it is one central point (compared to a bunch of independent repositories). Good because it is independent on GitHub.

Bad because compared to GitHub wiki it is heavyweight. Bad because it is it an unexpected place from POV of someone who stumbles upon any YaST Git repo.

Personally, I'd prefer to use GitHub wiki of appropriate repositories (devtools, ...).

--
David Majda
SUSE Studio developer
http://susestudio.com/
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups