Repository structure, binaries and sources

Vanuan commented 12 years ago

Usually, a git repository contains only sources. Documentation is handled separately. PDF documents are usually hosted on a website. Doxygen documentation is rarely checked into the source repository.

Proposals:

Add a separate repository for generated documents (PDF and doxygen) and/or add a branch gh-pages in this repository (http://pages.github.com/) to setup http://ivilink.github.com with api documentation.
If source documents for PDF are plain txt files, they can be checked in.
Remove doc folder from the main repository and move all the sources to root folder.

Additional comments:

It would be great if luxoft provided a full git history, not just "check in version 1", "check in version 2" commits. Providing only major versions on github is no different than hosting an archive with sources on a website.

Vanuan commented 12 years ago

Additionally, one big for all repo is not good. It would be better to divide it to multiple submodules.

SergeyDmitriev commented 12 years ago

I vote for this proposal. It looks very reasonable.

Vanuan commented 12 years ago

I've already implemented some of these: https://github.com/ivilink

Moved the generated documentation to github pages: http://ivilink.github.com/ (source) Moved the copyright console application to separate repository: https://github.com/ivilink/copyrightcons

kostiakhait commented 12 years ago

That's the bad practice to keep documents out of the code for commercial projects or wider for projects you commit to support. You shall be sure which documents are released to which version of code/binaries to refer to the proper ones communicating to clients and external stakeholders. Therefore, documents must be kept in alignment with code and other artifacts. It doesn't mean that it is not needed to put documents to web page and/or WiKi where it will be easy to read or download it. But the main principle is all project assets must be stored and tagged together.

kostiakhait commented 12 years ago

Guys, I also kindly ask you to mark your changes properly, i.e. keep it under "proposal" status until accepted and integrated to the iviLink mainstream. I am really happy we have independent community, but please be accurate as we still need to have this project controlled, especially in configuration management. Let's separate proposals, custom forks and approved changes, mark source code and side resources with proper notes and follow copyright policies. Thanks in advance.

Vanuan commented 12 years ago

@kostiakhait Please notice that I don't propose to keep documents out of code. I propose to keep generated documents out of source repository.

Therefore, documents must be kept in alignment with code and other artifacts

git submodules provide you exactly that. Each revision in code repository has a link to the specific revision in docs repository: https://github.com/ivilink/iviLink/commit/cb630168383ea260761ba2fdc3299e99026bfda2

More info on submodules: http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html

But the main principle is all project assets must be stored and tagged together.

They would still be stored together. Just in separate repositories.

Generating documentation before each commit is not productive, don't you agree?

Vanuan commented 12 years ago

Let's separate proposals, custom forks and approved changes, mark source code and side resources with proper notes and follow copyright policies.

What do you mean? What you want to be marked and where? Which copyright do you see infringed?

kostiakhait commented 12 years ago

My understanding ivilink.github.com is not an official iviLink resource approved by the keeper of iviLink trademark rights. I don't treat it as trademark violation, but definitely this should be clearly noticed. It is excellent if you do things better, just separate what is official and what is a proposal.

Vanuan commented 12 years ago

I've added a copyright notice: https://github.com/ivilink/ivilink.github.com/commit/f7af66edab5b0ce94eee7f7f9e43a675ff3eb130

You can make any further changes by pushing to the website repo: https://github.com/ivilink/ivilink.github.com

Vanuan commented 12 years ago

BTW, where can I suggest changes to the http://www.ivilink.net/ ? GetSDK button doesn''t work.

yshvalik commented 12 years ago

I've added a copyright notice: https://github.com/ivilink/ivilink.github.com/commit/f7af66edab5b0ce94eee7f7f9e43a675ff3eb130

You can make any further changes by pushing to the website repo: https://github.com/ivilink/ivilink.github.com

Thank you for adding copyright notice. I want also to ask you to change the name of "Organization" mentioned at https://github.com/ivilink. Now it has just iviLink name. Please change it to something like "Unofficial iviLink community" to make sure everybody distinguish it from official version. Otherwise it can bring confusion to the people we’re already presenting the technology. And finally please refer URL at the main page to http://ivilink.github.com Thanks.

Vanuan commented 12 years ago

Done

Luxoft / iviLink

Repository structure, binaries and sources #3