We currently keep our coding standard in a MSWord document under SVN.
As our standards grow / change, it's becoming an increasingly clunky beast to maintain.
Most entries currently consist of:
A succinct explanation of the guideline.
Reasoning behind the guideline.
Any extra notes.
Examples of what you should do.
Examples of what you should not to.
At the moment we use track changes within the document to keep track of pending suggestions / corrects which are periodically reviewed and then accepted / rejected.
Is there a de-facto good way of tackling maintaining a document like this?
A repository at GitHub would serve well. See example: https://github.com/airbnb/javascript - you can have discussions, track changes, accept/reject pull requests, etc.
Also it would help if you use auto-formatting tools plugged into your build process like https://golang.org/cmd/gofmt/ or https://github.com/thoughtbot/hound
I suggest you use plain text file (or HTML / some other markup file if you need some fancy formatting) under some version control system. We used Word's features for versioning and I like what Git offers much much more.
GITHUB: As an organization, if you maintain a private Github repository (not opensource, but leverage Github's strengths to maintain repository, allow distributed coding accessible to individuals within organization), you could upload your Coding Standards document to a Github repository, maintain a markdown document, which could have reviews/pull requests etc, as mentioned by Alex above
REVIEWBOARD: If your organization does not have a private Github repository, then I suggest you could choose this option, if your organization is performing code reviews through review board. ReviewBoard allows to review code by peers, maintain data of the different reviews, whether addressed, whether the version is allowed to be shipped etc. So, you could avail this feature of review board to review Coding Standards document. ReviewBoard has a feature of reviewing PDF documents. So, I guess by this option, you are maintaining a repository for CodingStandards document as well as providing an option of reviewing PDF document, which is tracked by ReviewBoard application.
Hope it helped. I guess there might be many other ways in which many companies might be doing.
Related
Are there best-practice guidelines for maintaining a GitHub repository? I've contributed to many open source projects and used GitHub for projects that I work on solo, but now I'm working with a team of six developers, including myself, to build a system, and I've been placed in charge of maintaining the repository. Nothing is to get merged into our main branch without my approval. As little as I know about maintaining a GitHub repository, of those within the organization (two team members are consultants) I've the most experience with the process.
But I've never maintained a GitHub repository, and while I'm doing OK, I know that there must be a body of knowledge out there of how to handle this correctly. I just haven't been able to find it.
One hurdle I've been jumping over repeatedly, for example, is merge conflicts. Usually they're minor, but not always. Is there some known system available that allows me to enforce who has the ability to edit which files at any given time, for example?
And yes, I realize this may not be the best Stack Exchange forum, but none of the others seemed more suited to the topic.
The Cloud Native Computing Foundation (CNCF) serves as the vendor-neutral home for many of the fastest-growing open source projects, including Kubernetes, Prometheus, and Envoy.
As such, it can be used as a starting point for your own project: see contribute.cncf.io/maintainers/github/, which offers:
template, to be usre you have your README, LICENSE and other important files.
labels, to better classify your issues
Add also a clear "release and maintenance policy", and you should be in good shape.
Consider two repos, webui_repo and webservice_repo, that are two interdependent systems (the web UI and service, respectively).
As you can imagine, the webui depends on webservice, but imagine that they've grown a lot and are managed by two teams, thus a considerable amount of effort is required to get things going, and that's ok.
But sometimes one of them gets deployed and either breaks retro-compatibility or expects a feature that hasn't been deployed yet. In order to alleviate that, I thought of a dependency-check feature, based on commit keywords (similar to closing issues using keywords):
This is my commit message. Depends on: webservice_repo/commit/<commit_hash>
I've done a small research and couldn't find any existing feature that provides this. I've also tried to find out if Github provides any extension/customization to the merge process, but no answer there as well.
Any ideas?
Even though I still think this should be a GitHub's feature, I have written a small web app to provide this functionality: Pierre DeCheck
I hope it's useful to more people. Also, it's open source, start contributing already! :)
I'm considering moving my open-source project Flyway from Google Code to GitHub.
One of the features I really like in Google Code's Issue Tracker is the ability to vote and sort issues by the number of votes. This has allowed me to get a good feel of where current pain points lie and what the community feels needs attention or further work.
How can I achieve something similar on GitHub? Is there a way to maintain a democratic approach to Issue Tracking?
There is no built-in ability to do so. Technically speaking, you can only manage issues by
assignee
tags (called labels at github)
milestones
While you can define label systems for lots of differentation criteria like
bug/feature request/...
prio high/low/...
status verified/unverified
it is simply not possible to have something that accumulates votes. So typically you will see "+1" postings as in good old mailing lists. I've seen people using external voting systems (like Google moderator) for issues on github, but that doesn't make a good user experience either.
If you're willing to use a third-party system that integrates with GitHub, you can try GitPoll.
Once again, I'm a bit stumped about the best stack-exchange site on which to post this question. But I think developers are best suited to answer questions about source control, so here it is.
I am considering a crowd-sourced, user-rated game development project and am wondering what, if any, source control and merging systems might best be capable of hosting the kinds of source control I'm interested in. By user-rated, I mean that there will be some kind of rating/voting system like that found here on StackOverflow. For some details on the project idea, you can read my posting about it at http://gamedev.enigmadream.com/index.php?topic=1589.0. What I think I need is:
Ability to branch by user and maximize merging capabilities. I know source control systems are mainly focused on branching by version, and we could maybe think of each user maintaining their own version. But I guess we need some really robust merging capabilities to maximize the abilities of one user to merge changes from another user into their own branch, for example. So I think I would like the ability for "cross-branch" merging without having to merge into the common root branch first. (I'm most familiar with Team Foundation Server (TFS), which doesn't easily support this.)
Massive branching and merging. If there are hundreds or thousands of people wanting to incorporate their own changes into the project, there could be a lot of branches, and the system would need to be able to handle that without a meltdown. A single user might want to create multiple branches deriving from multiple other users' branches under their own name too, ideally, with the ability to merge among them to some extent.
Permission control by branch. I see SourceForge supports Subversion and Mercurial, but does not currently support permission controls by path/branch on these (as far as I can tell), although that does appear to be a feature under consideration. Users should be limited from pushing their code into other branches. I suspect the normal operations for a user would be pulling edits from other branches into their own branch, and checking in additional changes in their own branch.
A voting system. I know I shouldn't expect a source control system to support voting natively, but anything that could contribute to making this possible would be helpful. For example, maybe a voting system would involve or rely on the ability to label the best edits from various branches and pull them into a single file based on a label or a set of labels. And anything that would assist in merging the results of a selected set of labels from various branches (perhaps applying a new label to the set) could help too.
Very few files and possibly no directories. I would be willing to give up the ability to manage a large number of files or directories in exchange to gain any of the above because the format for the game file I'm considering is generally contained in a single text (XML or HTML5 -- haven't decided yet) file. But this does mean that the system should be pretty good at merging edits to relatively large text files efficiently. I know Team Foundation Server does a pretty good job of maintaining just changes to a file. I hope other source control systems do at least as well.
Or is source control not the proper paradigm to be talking about here? Is there some other technology ideal for merging code like this, one that doesn't involve source control and/or branching the way I'm thinking about it?
Any VCS, because "...source control systems are mainly focused on branching by version..." is just wrong, VCS support diverged changes of code over time, nothing more and nothing less
Any DVCS, because they have reasonable good branch-merge capabilities from the ground
Mercurial, which have branch-level ACLs, SVN have path-based ACLs. And because Subversion have physical tree repository (at some degree), ACLs can be applied to any part of subtree, i.e to branches also
Any CodeReview tool, integrated with VCS and modified for specific-reqs
Fossil SCM is single-file portable EXE, repo - one file; any DVCS also add only one dir of repo to existing tree and handle big files without headache
Ok, when hired on to my current company a year ago, I was tasked with migrating our development teams from VSS. They already had it in their minds that they wanted Subversion, and since I had experience using and setting up subversion, I was a good candidate. I first tried to sell TFS because it woul dhave solved the problem I am in right now, but since money is tight, and Subversion is free... well you get it. Anyway, I have finalized the propsal and the only thing standing in the way is the following.
I proposed that we store only our source code in SVN, and all documentation, release builds, and other project artifracts be stored in our SharePoint portal, so we don't have to give non developer stakeholders access to SVN. When I presented the proposal, all was excepted but the question arose about how to manage the syncronization between the artifacts (Ex: How to is document x version 3.1.2 associated with release 4.5.2). My initial reaction is to create a section in the SharePoint porject page for each new release that will hold the artificats (and keep track of changes too). Is there a better way of doing this? Does anyone know of anyone doing this? Or any integration packages to sync SVN with SharePoint?
Here is some info on the companies development environment. All of our software is for internal use, we sell none of it, so our customers are all in-house. We have 2 types of developers: 1. those who take care of maintainance and customization of third party software, and 2. those who write proprieatry software (which is where I fall). Our software we write is mostly .NET, but the 3rd party software is all over the board (COBAL, C, FORTRAN, Other crap that no ones cares about anymore).
Please advise, as I need to get this submitted soon. I HATE VSS!!!!!!!!!! and I need relief!
What we do internally is putting all docs under our version control system, I think it's much easier. Then, of course, you have to give access to not-developers.
In your case, using SVN, why don't you put everything inside and then use the webinterface to give access to the stakeholders? It's easy enough for them :-P
I would use SVN for both documents and source code.
Advantages:
You can synchronize versions of
documents with versions of source
code.
You have everything in one place, so
no two repositories to administrate.
Disadvantages:
You'd probably need to manage the
access rights for some stakeholders
to some parts of the folder
structures.
SVN is not the most appropriate tool
for document management
In order to solve the possible concurrent changes to the same document, you can use SVN property svn:needs-lock for these items, to make them editable by one person, who locks the item.
As pablo said, you can access the documents (at least for reading them) through the web interface.
You could expose the svn repo via the web interface and link to that in sharepoint. That way people who need to edit the documents would need access to subversion but anyone could easily access the documents "read only".
In our organization, we have docs/artifacts, code everything in SVN and have given access to non-technical stakeholders as well who use tortoise client.
however you can look at the following option
Option 1 : create a ASP.Net interface for non-technical users
You can build a simple web interface in ASP.net, configure that with a single user so you would not have to create separate users for all the nontechnical stakeholders and they would get access to the docs with proper version control, etc. you could look at sharpsvn for the implementation aspect. the disadvantage of this approach would be that you might have to invest some time in developing this app
Option 2 : ofcourse, create separate users for each non-developer stakeholder
This answer is probably too late for you implementation, but the simplest integration path may be to store the docs in SVN and then publish to Sharepoint with an svn-hook.
Build artifacts could be programatically published the same way from you build scripts.
You can upload docs to SharePoint using a simple POST
i.e.
http://blogs.msdn.com/rohitpuri/archive/2007/04/10/upload-download-file-to-from-wss-document-library-using-dav.aspx
Probably a little late, too, but I would avoid putting the documents in SVN if you have a SharePoint system setup. Though SVN does a fantastic job for source code, for document management it doesn't provide the ease-of-use of SharePoint. If you have it already setup and you are a primarily MS based network, SharePoint makes a lot of sense and can handle revision control for the MS based documentation much better than SVN.
Yes, you can manage access to SVN documents with a needs-lock, but chances are at some point you'll have a non-developer needing to access the documents. Explaining SVN to a non-developer, non-techie is not an easy thing.