Hi,
When Christopher was in Prague, a few of us had a brainstorming about
the need of having devel-documentation placed directly in a
Yast/libstorage/linuxrc repository. There are no doubts that it's one of
the most important parts of projects hosted at GitHub. All their howtos
mention "create README[.md]" as the very first step.
In fact, we'll have new hires in the team and in such situations, good
documentation is one of the most important parts. Good documentation
goes from very high level to lower and lower level.
We have already summarized that in Yast Team Challenges, but the summary
doesn't belong to this document as it's too detailed. That's why I'm
putting it here as a WIP item and deleting it from that document:
--- cut ---
The README should at least describe the steps needed for maintenance
(for a person without expert knowledge in the area) including:
* What is the project good for - what does it actually do (and how),
what it cannot do (unsupported scenarios), limitations
* Links to the documentation, high level and low level descriptions
(e.g. RFC, wikipedia articles, man pages, project documentation,
openSUSE wiki), terminology
* How to fetch the source code (if something outside Git is needed it
should be mentioned)
* What prerequisites are needed to build the sources (external
libraries, gems, scripts, …)
* How to build the sources (make/rake commands…)
* How to setup a testing environment (e.g. iSCSI target for iSCSI
client)
* How to run the code to test a change (esp. needed for non trivial
projects like linuxrc)
* How to run automated tests
* How to build a package for submission
* How to submit the package (if it needs some manual steps)
* Troubleshooting (how to solve typical problems)
The README should be reasonably short, if some section is too long it
should be moved to a separate document (or to GitHub wiki) and linked.
--- cut ---
The project consists of
- Taking a decision where to go
- How to get there
- Implementing this important documentation
Those two who, according to my knowledge, were working on this were
Ladislav and Christopher, but there were not the only ones and a pilot
project for READMEs has been done a few months ago by Martin. It's still
not finished, but moving forward.
Thanks
Lukas
--
Lukas Ocilka, Systems Management (Yast) Team Leader
SLE Department, SUSE Linux
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
We are now working on a launch of a new translation server:
https://l10n.opensuse.org/
We just added first few projects, but we plan to migrate all
translations there after the beta phase.
Benefits:
No more need for picking pot from GitHub, uploading it to LCN SVN,
waiting, picking translations back. Weblate is built on top of GIT, and
translation can be automatically uploaded to GIT. Imagine that openSUSE
LCN SVN has projects, where nobody picked translations for 7 years!
Weblate features translation merge across branches. We can create common
translation covering both SLE and openSUSE. No more divergences in
translations.
The only work on developers side is (in the current version) updating of
po files against the latest pot and pushing it to the git repo. (And
even it can be automatized in future.)
What will be needed before YaST can be added to Weblate:
1) Decide how YaST will manipulate with po files. Currently all po files
for all repositories reside in a single repository (and later in a
single package). It was useful in time of manual downloads and uploads,
where no -lang package merging was implemented. Now it will complicate
fully automatic work flow, as pot files needs to be transferred across
repositories (at least until somebody invents a robot for it).
2) Decide how YaST will accept translations.
Standard way is an automatic pushing of translations to git using rules
defined by Weblate (currently 100% reached or no changes in last 2
hours) by dedicated user (opensuse-i18n). I was pointed to the problem
that YaST developers may need to review some strings and edit their test
suites. I guess that there can be techniques that can help with watching
of such special changes. But in general, I think that developers have no
chance to review translations.
Another way is pull request (GitHub only). With pull requests,
developers will get pull request on each change mentioned above.
Pull request could possibly add a lot of work to you. Imagine, that 50
modules with 16 languages can generate nearly 1000 pull requests in on
translation round.
Third way is manual pulling from the Weblate on request. I would avoid
this as much as possible. If you update po files in GitHub, you will get
conflict, and problem would need manual git merge.
3) Have cleanly defined branch for SLE (and possibly other projects).
I guess it is already done in a such way:
All projects, where translations are maintained in parallel for
different versions, need to have branch in the repository. Weblate will
then be able to push the correct po file to each branch.
4) Merge openSUSE and SLE translations.
openSUSE and SLE translations diverged over the time, as there is no
merging process. Translation team agreed on merge of both.
The merge is planned to be performed on Weblate side:
3a) GitHub will import openSUSE translations.
3b) Weblate will import SLE translations as change suggestions.
3c) Translators will be asked to perform review.
3d) The standard process will post merged translations to GitHub.
Technical details:
Steps that need to be done on import to Weblate:
1. The last import from LCN SVN trunk branch will be done.
2. po and pot files will be removed from LCN SVN trunk branch.
3. These translations will be pushed to GitHub (one shot).
4. Weblate web service (in GitHub webhooks) will be added to each
project configuration.
5. opensuse-i18n robot will be allowed to push to your project (not
needed in case of pull requests)
6. Project will be imported to l10n.opensuse.org
7. master branch will be added to that project
8. The last import from LCN SVN SLE branches.
9. po and pot files will be removed from LCN SVN SLE branches.
10. Particular SLE branches will be added to that project.
11. These translations will be added to Weblate as suggestions.
12. Translators will be asked for review and string merge.
13. When the merge will happen, robot will push merged translations to
GitHub.
--
Best Regards / S pozdravem,
Stanislav Brabec
software developer
---------------------------------------------------------------------
SUSE LINUX, s. r. o. e-mail: sbrabec(a)suse.com
Lihovarská 1060/12 tel: +49 911 7405384547
190 00 Praha 9 fax: +420 284 084 001
Czech Republic http://www.suse.cz/
PGP: 830B 40D5 9E05 35D8 5E27 6FA3 717C 209F A04F CD76
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
This email is automatic generated from yast CI node. It lists of pull requests that have no activity more then three working days. If your module is listed, please check all pull request, why they are not merged yet.
Pending requests in repository yast-country:
- Ensure ntp is installed (when Install Recommended Packages is off) (20 days)
https://github.com/yast/yast-country/pull/55
Pending requests in repository yast-slide-show:
- Sle 12 sp1 (7 days)
https://github.com/yast/yast-slide-show/pull/9
Pending requests in repository yast-storage:
- Propose /boot for encrypted root on PowerPC (42 days)
https://github.com/yast/yast-storage/pull/155
Pending requests in repository autoyast-integration-test:
- Test that network settings are applied (bsc#949193). (7 days)
https://github.com/yast/autoyast-integration-test/pull/42
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
Hi,
let me do some high level user oriented review of new storage API.
At first I think it is good that design decisions are documented, which
is nice. Also having goals and requirements is documented which is fine
to understand some decisions. What I miss is all requirements, I think
it would be nice to write down all features old libstorage have and
maybe discuss if it still make sense in new libstorage.
Now first note. I do not see in decisions why C++ is used as language
for this library. I think it would be nice to document it why it is
needed as currently from document I see that planned users are machinery
( which use ruby ), Yast (ruby) and kiwi (perl). Is there any
performance reasons, availability of bindings, libraries or any other
reason to use it? As libstorage basically use CLI of other programs, so
question is why not use more high level language.
Now lets move to examples. From my user POV there is some confusing API
calls and parameters. For example lets use find1.cc as example which I
comment (I can do this for all examples).
// creating some global storage is fine
Devicegraph* devicegraph = new Devicegraph();
// this looks strange for me
// 1) how disk can be created? I expect disk is detected or proposed
// 2) why saying that disk have "/dev/sda" what if I am on qemu which
// have "/dev/vda"?
Disk* sda = Disk::create(devicegraph, "/dev/sda");
// this looks fine for me, creating partition table on disk
PartitionTable* gpt = sda->create_partition_table(PtType::GPT);
// here I do not get why I need to pass "/dev/sda1" ? Let me say it
// this way, if I have generic code that generate partition for passed
// partition table how I can know if it is hda, sda or vda? and why
// I need to know number of partition? cannot it by default create next
// available one and pass number as optional parameter?
gpt->create_partition("/dev/sda1", PRIMARY);
Partition* sda2 = gpt->create_partition("/dev/sda2", PRIMARY);
// here I create top level container, looks fine for me
LvmVg* system = LvmVg::create(devicegraph, "/dev/system");
// this is very confusing, why I need devicegraph here? Why exposing it
// to user? From doc I know that both sda2 and system have reference to
// it so why it need to be passed?
// And also why it need User::create? Why it is not simple
// `system.add(sda2)` call which is more intuitive for me?
User::create(devicegraph, sda2, system);
// in general it looks fine for me, just is there reason to pass
// whole device name? who not having thing like
// `system->create_lvm_lv("root")`
LvmLv* system_root = system->create_lvm_lv("/dev/system/root");
// creation of filesystem, intuitive and easy
Filesystem* filesystem = system_root->create_filesystem(EXT4);
// quite confusing, what is adding mountpoint to filesystem?
// filesystem do not know about mount points, I expect something like
// `devicegraph.mountpoint.add("/", filesystem)`
filesystem->add_mountpoint("/");
// some debug output, nothing to comment, not sure if it is needed to
// be public methods
cout << "num_devices: " << devicegraph->num_devices()<< endl;
cout << "num_holders: " << devicegraph->num_holders() << endl;
cout << endl;
// validation of storage, easy and intuitive... does it raise exception
// if failed?
devicegraph->check();
// printing of object, fine and intuitive C++ code
cout << devicegraph << endl;
// printing graphiz image, easy and intuitive API call
devicegraph->write_graphviz("test1.gv");
// looking for all filesystems that are mounted as root mountpoint
// is confusing. why it do not return single filesystem?
for (const Filesystem* filesystem : Filesystem::find_by_mountpoint(devicegraph, "/")) {
// I am not sure if I can imagine what is ancestor of filesystem?
// I hope there is better name for it
// second note is boolean parameter, it is really hard to read it and
// hard to remember what such parameter mean. see e.g
//http://programmers.stackexchange.com/questions/147977/is-it-wrong-to-use-a-boolean-parameter-to-determine-behavior
for (const Device* device : filesystem->get_ancestors(false)) {
// this a bit break polymophysm, but it is explained in design
// document, so fine for me
if (dynamic_cast<const LvmLv*>(device))
cout << "mount point \"/\" somehow uses a logical
volume" << endl; }
}
delete devicegraph;
So in general, I think that we should now more focus on API and its
usability as it is hard to change it in future. When having good API,
some cleaning or refactoring of implementation later is easier
( current code in new libstorage is short and easy, but I worry in
future with more features, we need to be prepared to clean it also).
I think it make sense to write down an example ( or better test case in
something like rspec) for each requirement and talk how its usage looks
for target user and if it easy to use and intuitive. Also this examples
can be something to show for review for potentional users of library
and they can said if it fits their needs or if they missing something.
Josef
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
This email is automatic generated from yast CI node. It lists of pull requests that have no activity more then three working days. If your module is listed, please check all pull request, why they are not merged yet.
Pending requests in repository yast-country:
- Ensure ntp is installed (when Install Recommended Packages is off) (19 days)
https://github.com/yast/yast-country/pull/55
Pending requests in repository yast-slide-show:
- Sle 12 sp1 (6 days)
https://github.com/yast/yast-slide-show/pull/9
Pending requests in repository yast-storage:
- Propose /boot for encrypted root on PowerPC (41 days)
https://github.com/yast/yast-storage/pull/155
Pending requests in repository autoyast-integration-test:
- Test that network settings are applied (bsc#949193). (6 days)
https://github.com/yast/autoyast-integration-test/pull/42
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
This email is automatic generated from yast CI node. It lists of pull requests that have no activity more then three working days. If your module is listed, please check all pull request, why they are not merged yet.
Pending requests in repository yast-country:
- Ensure ntp is installed (when Install Recommended Packages is off) (16 days)
https://github.com/yast/yast-country/pull/55
Pending requests in repository yast-storage:
- Propose /boot for encrypted root on PowerPC (38 days)
https://github.com/yast/yast-storage/pull/155
- don't create btrfs subvolumes outside the root fs (bsc#940797) (28 days)
https://github.com/yast/yast-storage/pull/148
Pending requests in repository autoyast-integration-test:
- Check Kdump configuration with multiple crashkernel options (14 days)
https://github.com/yast/autoyast-integration-test/pull/30
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
This email is automatic generated from yast CI node. It lists of pull requests that have no activity more then three working days. If your module is listed, please check all pull request, why they are not merged yet.
Pending requests in repository yast-core:
- More diagnostic info when we get a signal (6 days)
https://github.com/yast/yast-core/pull/102
Pending requests in repository yast-country:
- Ensure ntp is installed (when Install Recommended Packages is off) (15 days)
https://github.com/yast/yast-country/pull/55
Pending requests in repository yast-storage:
- Propose /boot for encrypted root on PowerPC (37 days)
https://github.com/yast/yast-storage/pull/155
- don't create btrfs subvolumes outside the root fs (bsc#940797) (27 days)
https://github.com/yast/yast-storage/pull/148
Pending requests in repository yast-auth-server:
- Drop ca mgm (114 days)
https://github.com/yast/yast-auth-server/pull/21
Pending requests in repository autoyast-integration-test:
- Check Kdump configuration with multiple crashkernel options (13 days)
https://github.com/yast/autoyast-integration-test/pull/30
--
To unsubscribe, e-mail: yast-devel+unsubscribe(a)opensuse.org
To contact the owner, e-mail: yast-devel+owner(a)opensuse.org
